Developer API

Build With The thecrimsonmarket.com Discord Bot

Developers can create an app in TCM and use approved OAuth scopes to manage the Discord servers they already control, read useful bot data, and receive webhook events for automations outside Discord.

Open Developer PortalView Bot Features

Setup Steps

  1. Step 1

    Create an app in the TCM developer portal.

  2. Step 2

    Make sure the app owner has a TCM account with Discord linked.

  3. Step 3

    Request the Discord bot API scopes your app needs for read or management actions.

  4. Step 4

    Use OAuth to get an access token for the service.discord audience.

  5. Step 5

    Call API endpoints from your backend. Management calls are checked against the app owner's Discord server permissions.

Available APIs

The API is designed to support the same server-owner workflows as the dashboard. Read scopes can power public giveaway directories, community websites, stats pages, server comparison tools, and custom dashboards. Management scopes can update settings only for servers the app owner is allowed to manage.

GET/mana/discord/api/v1/status

Check that the Discord bot API is reachable.

Scope: discordbot:read

GET/mana/discord/api/v1/giveaways

List public active giveaways across servers using the bot.

Scope: discordbot:read

GET/mana/discord/api/v1/me/guilds

List bot servers the app owner can manage based on their linked Discord account and server permissions.

Scope: discordbot:manage

GET/mana/discord/api/v1/guilds/{guildId}

Read safe public status for a Discord server using the bot.

Scope: discordbot:read

GET/mana/discord/api/v1/guilds/{guildId}/management

Read dashboard-equivalent configuration data for a server the app owner can manage.

Scope: discordbot:manage

GET/mana/discord/api/v1/guilds/{guildId}/giveaways

List giveaways for one server.

Scope: discordbot:read

GET/mana/discord/api/v1/guilds/{guildId}/levels/leaderboard

Read server leveling leaderboard data.

Scope: discordbot:leaderboards:read

GET/mana/discord/api/v1/guilds/{guildId}/economy/leaderboard

Read server credit economy leaderboard data.

Scope: discordbot:leaderboards:read

GET/mana/discord/api/v1/guilds/{guildId}/economy/credits/{discordUserId}

Read a member's spendable server credit balance for a server the app owner can manage.

Scope: discordbot:economy:read

POST/mana/discord/api/v1/guilds/{guildId}/economy/credits/adjust

Add, remove, or set server credits from an external system using an idempotent transaction ID.

Scope: discordbot:economy:write

POST/mana/discord/api/v1/guilds/{guildId}/giveaways

Create a giveaway for a server the app owner can manage.

Scope: discordbot:giveaways:write

PATCH/mana/discord/api/v1/guilds/{guildId}/leveling/config

Update server leveling settings, including level roles and level-up webhook rewards.

Scope: discordbot:leveling:write

PATCH/mana/discord/api/v1/guilds/{guildId}/economy/config

Update server economy settings, including reward shop purchase webhooks.

Scope: discordbot:economy:write

GET/mana/discord/api/v1/guilds/{guildId}/commands

Check slash-command registration status for a server the app owner can manage.

Scope: discordbot:manage

POST/mana/discord/api/v1/guilds/{guildId}/commands/refresh

Refresh slash commands for a server the app owner can manage.

Scope: discordbot:manage

Owner-Scoped Server Management

A developer app should not become a global bot admin key. The app is tied back to its TCM owner, and that owner's linked Discord ID is used to determine which servers they can manage.

Permission Model

  • The developer app belongs to a Portal user account.
  • That user account must have a Discord ID stored through linked account data.
  • The API uses that Discord ID to find which bot servers the app owner can manage.
  • For each guild action, the bot verifies the owner is still a member and has the required Discord permissions, such as Manage Guild or an equivalent admin-level permission.
  • Scopes limit what the app is allowed to do even when the owner has Discord permission.

Management Use Cases

  • Create, edit, end, reroll, and export giveaways.
  • Read and update server leveling, rank card, level role, and level-up webhook settings.
  • Read and update server economy, reward shop, purchase webhook, and leaderboard settings.
  • Read server credit balances and let approved third-party systems add, remove, or set server credits with idempotent transaction IDs.
  • Configure welcome, verification, role panels, tickets, logs, moderation, automations, scheduled messages, and alerts as those API scopes are exposed.
  • Read command registration status and trigger command refresh for servers the app owner can manage.

Webhook Integrations

Server owners can also configure outbound webhooks from the dashboard. These are useful when the owner wants their own server to react to bot activity without polling the API.

discord.level_up

Sent when a member reaches a new server level. Includes guild ID, Discord ID, username/display name, previous and current level, XP totals, source, role rewards, and credit rewards.

Supports API key header and optional HMAC SHA-256 signature.

discord.level_role_reward

Sent when a configured level role reward is actually awarded. Includes guild ID, Discord ID, username/display name, previous and current level, reward level, XP totals, source, and the Discord role ID/name.

Supports API key header and optional HMAC SHA-256 signature.

discord.reward_purchase

Sent when a member buys a reward shop item. Includes guild ID, Discord ID, item details, purchase ID, status, price, role reward details, and remaining balance.

Supports API key header and optional HMAC SHA-256 signature.

What Apps Can Safely Do

Show Giveaways

Build public pages that help servers promote active giveaways and grow their Discord communities.

Display Progress

Show level leaderboards, rank point standings, and economy leaderboards outside Discord.

Manage Authorized Servers

Apps can be allowed to perform dashboard-style actions for servers where the app owner has the required Discord permissions and the app has the matching OAuth scope.