Noctra Public API

Prerequisites

• Valid Discord Bot Token (validated live against Discord API)
• Bot must be a member of the target guild
• S3-compatible object storage configured on the server

Required Headers

Responses

{"success":true,"message":"Warn logged.","viewUrl":"https://api.noctra.xyz/api/modlogs/view/..."}

{"error":"Headers required."}

{"error":"Bot token invalid."}

{"error":"Bot not member."}

{"error":"Internal error."}

Use Cases

• Recording a warn/ban/kick/timeout from an external moderation dashboard and posting the viewUrl in a Discord channel for staff reference
• Building a persistent moderation history per user per server, accessible via a shareable HTML page with search and filtering
• Automating moderation logging from a custom Discord bot that performs actions and needs an audit trail

Prerequisites

• BAN_MEMBERS permission for the bot
• Bot's highest role must be above the target user's highest role

Required Headers

Responses

{"message":"User successfully banned"}

{"error":"Missing headers"}

Use Cases

• Permanently remove a user who violated server rules via an external moderation dashboard
• Automated ban enforcement triggered by anti-raid or automod systems
• Bulk banning users identified by a spam detection pipeline

Related Endpoints

• Unban User — inverse

Prerequisites

• BAN_MEMBERS permission for the bot
• Bot's highest role must be above the target user's highest role

Required Headers

Parameters

Request Examples

{"reason":"Spam","deleteMessageDays":1}

Responses

{"message":"User successfully banned"}

Use Cases

• Banning a user with a documented reason that appears in the Discord audit log for accountability
• Removing a spammer and purging their last 7 days of messages in one operation

Prerequisites

• BAN_MEMBERS permission for the bot

Required Headers

Responses

{"message":"User successfully unbanned"}

Use Cases

• Reversing a ban after a successful appeal process
• Automated unban after a temporary ban period managed by an external system

Prerequisites

• KICK_MEMBERS permission for the bot
• Bot's highest role must be above the target user's highest role

Required Headers

Responses

{"message":"User successfully kicked"}

Use Cases

• Removing a disruptive user as a warning before escalating to a ban
• Automated kick for users who fail verification or age-gate checks

Prerequisites

• MODERATE_MEMBERS permission for the bot
• Target user must not be an administrator or server owner

Required Headers

Responses

{"message":"Timeout successfully applied","expiresAt":"2024-01-15T18:00:00Z"}

Use Cases

• Temporarily muting a user who is spamming in chat without removing them from the server
• Applying a cooldown period after a rule violation as a lighter alternative to a ban
• Automated timeout triggered by message frequency or content detection systems

Related Endpoints

• Remove Timeout — inverse

Prerequisites

• MODERATE_MEMBERS permission for the bot

Required Headers

Responses

{"message":"Timeout successfully removed"}

Use Cases

• Lifting a timeout early after a user submits a successful appeal
• Automated timeout removal when a moderation review determines the action was unwarranted

Prerequisites

• Valid Discord Bot Token
• Bot must have SEND_MESSAGES and EMBED_LINKS permissions in the target staff channel

Required Headers

Request Examples

Hello, I need help.

Responses

{"status":"Forwarded to staff"}

Use Cases

• Building a modmail system where user DMs are forwarded to a private staff channel for review and response
• Creating a support ticket flow where users contact staff without needing to be in the server's channels
• Forwarding reports or appeals from users to a dedicated moderation team channel

Related Endpoints

• Modmail Outbound — complementary

Prerequisites

• Valid Discord Bot Token
• Bot and target user must share at least one server
• User must have DMs enabled for the shared server

Required Headers

Request Examples

Issue resolved.

Responses

{"status":"Reply sent to user"}

Use Cases

• Replying to a user's modmail ticket from a staff command or dashboard interface
• Sending automated follow-up messages to users after their support request is resolved

Prerequisites

• VIEW_CHANNEL permission for the bot in the target channel
• Valid Discord Bot Token

Required Headers

Parameters

Responses

{"id":"987654321098765432","name":"general","type":0}

"Missing token, guildId, or channelId."

Use Cases

• Displaying channel settings and permissions in a management dashboard
• Auditing channel configurations such as slow mode, NSFW status, and permission overwrites
• Retrieving channel topic and type information for bot command routing

Prerequisites

• MANAGE_CHANNELS permission for the bot
• Channel must be a guild channel (not a DM channel)

Required Headers

Responses

{"success":true,"position":2,"category":"Text Channels"}

Use Cases

• Reorganizing server channel layout from a dashboard without manual drag-and-drop in Discord
• Moving a channel to a different category as part of an automated server setup or template system
• Reordering channels within a category based on activity or priority rules

Prerequisites

• Valid Discord Bot Token
• Bot must be a member of the target guild

Required Headers

Parameters

Responses

{"serverTag":{"isActive":false},"enhancedRoleStyles":{"isActive":true}}

Use Cases

• Displaying which boost perks are active on a server in a dashboard UI
• Determining if Enhanced Role Styles (gradient colors) are available before attempting to create gradient roles
• Monitoring boost perk activation status across multiple managed servers

Prerequisites

• Valid Discord Bot Token
• Bot must be a member of the target guild

Required Headers

Parameters

Responses

{"hasStandard":true,"hasColor":true,"hasGradient":false,"hasIcon":false}

Use Cases

• Determining which customization options to show boosters in a role-creation UI (color picker, gradient picker, icon upload)
• Gating booster role features in a dashboard based on the server's actual boost tier

Prerequisites

• MANAGE_GUILD permission for the bot
• Valid Discord Bot Token

Required Headers

Parameters

Responses

{"total_keywords":15,"keywords":"spam,scam,phishing"}

"Rate limit exceeded. Please wait 1 minute."

Use Cases

• Syncing automod keyword lists to an external dashboard for display and editing
• Auditing which words are blocked across multiple servers managed by the same bot
• Exporting automod configuration for backup or migration purposes

Prerequisites

• Valid Discord Bot Token
• Bot must have access to the guild containing the category

Required Headers

Responses

{"categoryId":"123","categoryName":"Text Channels","totalChannels":5}

{"error":"The provided ID is not a category channel"}

Use Cases

• Displaying a category's full channel structure in a server management dashboard
• Auditing permission overwrites across all channels in a category
• Building a visual channel tree for server configuration interfaces

Prerequisites

• Valid Discord Bot Token
• GUILDS and GUILD_VOICE_STATES Gateway intents enabled for the bot

Required Headers

Responses

{"channelName":"General","connectedUsersCount":5,"bitrate":64000}

{"error":"Voice channel not found"}

Use Cases

• Monitoring voice channel occupancy for a live dashboard showing who is in which voice channel
• Checking if a voice channel has available slots before directing users to join
• Displaying user voice states (streaming, camera, muted) in a server activity panel

Prerequisites

• MANAGE_ROLES permission for the bot
• Bot's highest role must be above the position where the new role is placed
• ENHANCED_ROLE_COLORS guild feature required for gradient colors (auto-fallback to solid color)

Required Headers

Responses

{"Message":"Role created successfully.","RoleId":"123456","GradientApplied":true}

"Guild not found."

Use Cases

• Creating roles programmatically as part of an automated server setup or template system
• Adding gradient/holographic roles for boosted servers from a dashboard interface
• Batch-creating roles with specific permissions for a moderation hierarchy

Prerequisites

• User must be a server booster

Required Headers

Parameters

Responses

{"message":"Booster role created successfully","roleId":"123"}

{"error":"User is not a server booster"}

Use Cases

• Custom booster roles

Prerequisites

• User must own the role being updated (validated via role assignment check)
• Valid Discord Bot Token with MANAGE_ROLES permission

Required Headers

Parameters

Responses

{"message":"Role updated"}

{"error":"You do not own this role"}

Use Cases

• Allowing a booster to change their custom role's name, color, or icon from a dashboard
• Updating gradient colors on a booster role when the server unlocks ENHANCED_ROLE_COLORS

Prerequisites

• User must own the role being deleted (validated via role assignment check)
• Valid Discord Bot Token with MANAGE_ROLES permission

Required Headers

Parameters

Responses

{"message":"Booster role deleted successfully"}

Use Cases

• Allowing a booster to remove their custom role when they no longer want it
• Cleaning up custom booster roles when a user stops boosting the server

Prerequisites

• MANAGE_ROLES permission for the bot
• Bot's highest role must be above the target role in the hierarchy

Required Headers

Responses

{"success":true,"totalMembersFound":25,"membersRemoved":25}

"Rate limit exceeded"

Use Cases

• Cleaning up a temporary event role after an event ends by removing it from all participants
• Mass-removing a role that was accidentally assigned to too many members
• Resetting role assignments as part of a periodic role rotation system

Prerequisites

• Valid Discord Bot Token
• Bot must be in the target server

Required Headers

Parameters

Responses

"Admin"

Use Cases

• Determining a user's effective permission level for display in a moderation dashboard
• Checking if a moderator outranks a target user before allowing moderation actions
• Displaying a user's primary role badge in a profile or leaderboard UI

Prerequisites

• Valid Discord Bot Token
• Bot must be in the target server

Required Headers

Parameters

Responses

"42"

Use Cases

• Displaying role member counts in a server management dashboard
• Monitoring role assignment growth over time for analytics
• Validating role-based access control configurations by checking member counts

Prerequisites

• GUILD_MEMBERS privileged Gateway intent enabled for the bot
• Valid Discord Bot Token

Required Headers

Parameters

Responses

{"RoleGroups":[],"AllMembers":{"TotalMembers":10}}

Use Cases

• Listing all members with a specific role for a role-based leaderboard or member directory
• Finding users who have multiple specific roles (e.g., both 'Verified' and 'Booster') using 'all' mode
• Building a role assignment report showing which members belong to which role groups

Prerequisites

• SEND_MESSAGES and EMBED_LINKS permissions for the bot in the target channel
• Valid Discord Bot Token

Required Headers

Parameters

Responses

"Message sent successfully."

"Rate limit exceeded. Try again in 8.5 seconds."

Use Cases

• Sending formatted announcements or notifications to a Discord channel from an external dashboard
• Posting automated alerts (e.g., server status, new content) as rich embeds with custom branding colors

Prerequisites

• Bot must be the author of the message being edited
• Valid Discord Bot Token

Required Headers

Parameters

Request Examples

{"targetContentSubstring":"old text","newContent":"new text"}

Responses

{"success":true,"message":"Component updated successfully."}

{"error":"No component found matching..."}

{"error":"Ambiguity: 2 components matching..."}

Use Cases

• Dynamically updating a specific section of a multi-component bot message (e.g., updating a stats counter) without rebuilding the entire message
• Editing bot messages from an external dashboard by targeting specific text content rather than tracking component indices

Related Endpoints

• Smart Edit Ephemeral — variant

Prerequisites

• Valid interaction token (expires 15 minutes after the interaction)
• Bot Application ID

Required Headers

Parameters

Responses

{"success":true}

Use Cases

• Updating the content of an ephemeral slash command response after additional processing completes
• Dynamically modifying a hidden interaction response (e.g., updating a progress indicator or status message)

Related Endpoints

• Smart Edit — variant

Prerequisites

• READ_MESSAGE_HISTORY permission for the bot in the target channel
• Valid Discord Bot Token

Required Headers

Responses

{"isFile":true,"fileType":"image/png"}

{"error":"Message or channel not found."}

Use Cases

• Enforcing image-only channels by checking if messages contain valid image attachments
• Building a media gallery bot that indexes file types from channel messages
• Detecting and logging file sharing activity for moderation purposes

Prerequisites

• Valid Discord Bot Token

Required Headers

Responses

{"days":1245,"weeks":177,"months":40,"years":3}

{"error":"Missing 'Discord-UserId' header."}

Use Cases

• Age-gating for server access
• Anti-raid detection of new accounts
• Trust scoring systems

Prerequisites

• Valid Discord Bot Token
• Bot must be a member of the target guild with permission to view member information

Required Headers

Responses

{"user_1":{"name":"Admin","role_position":1000},"user_2":{"name":"Mod","role_position":750},"comparison":{"user_1_higher":true}}

{"error":"User 1 not found on this guild"}

Use Cases

• Determining if a moderator can act on a target user by checking role hierarchy before executing a ban or kick
• Displaying permission comparison in a moderation dashboard to show who outranks whom
• Validating role-based access control before executing moderation actions from an external system

Related Endpoints

• Compare User Roles — variant

Prerequisites

• Valid Discord Bot Token
• Bot must be a member of the target guild

Required Headers

Responses

{"result":{"overall":"user-higher-than-all-roles"}}

Use Cases

• Validating if a user has authority over specific moderation roles before allowing them to perform actions
• Checking permission tiers in a multi-level moderation system (e.g., can this mod manage Trial Mods but not Admins)

Prerequisites

• Valid Discord Bot Token
• Bot must be a member of the target guild

Required Headers

Responses

{"id":"123","name":"My Server","owner_id":"456"}

Use Cases

• Displaying server overview information in a dashboard header
• Verifying bot access to a guild before performing other operations

Prerequisites

• Valid Discord Bot Token

Required Headers

Parameters

Request Examples

{"inviteLink":"https://discord.gg/E2pce4JTSK"}

Responses

{"inviteCode":"E2pce4JTSK","guild":{"name":"My Server"},"approximateMemberCount":1500}

"Invalid invite link."

Use Cases

• Previewing a Discord server before joining by resolving an invite link to show server name, member count, and description
• Analyzing invite links shared in chat to detect potential raid or scam servers
• Building an invite tracker that logs who created invites and how many members they brought

Prerequisites

• Valid Discord Bot Token
• Bot must have READ_MESSAGE_HISTORY permission in the source channel
• S3-compatible object storage configured on the server

Required Headers

Responses

{"message":"Transcript generated","messageCount":250,"directLink":"https://api.noctra.xyz/api/Transcript/view/...","viewId":"abc-123"}

{"error":"X-Bot-Token header is required"}

{"error":"No messages found in channel"}

Use Cases

• Generating a permanent transcript of a support ticket channel before closing it, with the link posted to a log channel
• Archiving important discussion channels as self-contained HTML files that can be viewed offline
• Creating moderation evidence transcripts that capture full message history including attachments and embeds

Related Endpoints

• List Transcripts — complementary

Prerequisites

• S3-compatible object storage configured on the server

Parameters

Responses

[{"viewId":"abc","channelName":"tickets","createdAt":"2024-01-15T10:00:00Z"}]

{"error":"Invalid guildId format"}

Use Cases

• Displaying a searchable transcript history in a server management dashboard
• Building a transcript browser with file sizes, creation dates, and creator information
• Implementing role-based access where moderators see only non-admin transcripts

Related Endpoints

• Generate Transcript — complementary

Request Examples

Hello "world"
New line

Responses

{"text":"Hello \"world\"\nNew line","characterCount":22,"stringified":"Hello \\\"world\\\"\\nNew line"}

"Request body must not be empty."

Use Cases

• Preparing user-generated text for safe embedding in JSON payloads sent to Discord webhooks
• Escaping multi-line text content before inserting it into a JSON template for embed descriptions

Parameters

Request Examples

{"text":"Very long text...","chunkSize":1800}

Responses

{"chunks":[{"index":1,"content":"...","length":1750}],"totalChunks":2,"chunkSizeUsed":1800}

{"error":"The text field is required."}

Use Cases

• Splitting long bot responses that exceed Discord's 2000-character message limit into multiple sequential messages
• Paginating log output or command results for display across multiple Discord messages

Required Headers

Parameters

Request Examples

{"pattern":"^\\w+@[a-zA-Z_]+?\\.[a-zA-Z]{2,3}$","input":"user@example.com"}

Responses

{"isMatch":true,"matchedValue":"user@example.com","error":null}

{"isMatch":false,"error":"Timeout: Operation took longer than 1s."}

Use Cases

• Testing and validating regex patterns for automod keyword rules before deploying them
• Checking if user input matches expected formats (emails, URLs, IDs) from a bot command

Parameters

Responses

{"unixTimestamp":1678886402}

"Unknown unit: weeks. Valid: seconds, minutes, hours, days, now."

Use Cases

• Generating Discord timestamp strings for bot commands (e.g., 'this event starts <t:1678886402:R>')
• Creating countdown timers by calculating a future timestamp and formatting it with Discord's relative time display

Parameters

Request Examples

{"Value1":["admin","mod","user"],"Value2":["mod","vip","user"]}

Responses

{"commonValues":["mod","user"],"isCommonFound":true}

Use Cases

• Finding common roles between two Discord users to determine shared access levels
• Comparing a user's role list against a set of required roles to check eligibility for an action

Prerequisites

• Avatar URL must be from an allowed domain (cdn.discordapp.com, imgur, imgbb, etc.)
• Background URL (if used) must also be from an allowed domain

Required Headers

Responses

{"success":true,"directImageUrl":"https://api.noctra.xyz/api/LevelCard/view/abc-123","imageSize":45000,"username":"JohnDoe","levelPercent":50.0}

{"success":false,"message":"Required headers missing","required":["Username","Avatar-Url"]}

Use Cases

• Generating a custom rank card for a Discord bot's /rank command that displays user level, XP, and stats
• Creating personalized level-up announcement images with custom colors and backgrounds
• Building a leaderboard system that generates visual rank cards for top users

Related Endpoints

• Welcome Card — similar

Prerequisites

• Background and avatar image URLs must be from allowed domains (cdn.discordapp.com, imgur, imgbb, etc.)
• S3-compatible object storage configured on the server

Required Headers

Responses

{"success":true,"directImageUrl":"https://api.noctra.xyz/api/WelcomeCard/view/abc-123","imageSize":85000}

{"success":false,"message":"Required headers missing: Background-Image and Profile-Avatar"}

Use Cases

• Generating a personalized welcome image when a new member joins a Discord server
• Creating custom member join announcements with server branding and member count
• Building a welcome card preview system in a dashboard where admins can customize colors and layout

Related Endpoints

• Level Card — similar
• Available Fonts — helper

Responses

{"success":true,"fonts":[{"key":"Arial","displayName":"Arial"}]}

Use Cases

• Populating a font selector dropdown in a card customization UI
• Validating font family names before sending card generation requests

Responses

{"version":"8.0.0-S3","system":"Smart Auto-Detect Encoding","allowedDomains":["cdn.discordapp.com"]}

Use Cases

• Understanding how to encode non-ASCII characters (e.g., Japanese, Arabic) in HTTP headers for card generation
• Checking which image hosting domains are whitelisted for background and avatar URLs

Prerequisites

• YouTube API Key for YT checks
• Twitch credentials for Twitch checks

Required Headers

Parameters

Request Examples

{"youtubeHandle":"@MrBeast","twitchUser":"xqc","tikTokUser":"khaby.lame"}

Responses

[{"platform":"YouTube","user":"@MrBeast","isLive":false},{"platform":"Twitch","user":"xqc","isLive":true,"title":"Stream Title","viewerCount":50000}]

Use Cases

• Live notification systems
• Stream status dashboards

Related Endpoints

• YouTube Check — single platform

Prerequisites

• YouTube API Key

Required Headers

Parameters

Responses

{"platform":"YouTube","user":"@MrBeast","isLive":false,"url":"https://youtube.com/@MrBeast"}

Use Cases

• Sending a Discord notification when a specific YouTuber goes live
• Displaying live status indicators in a streamer dashboard or bot command

Prerequisites

• Twitch Client ID and Secret

Required Headers

Parameters

Responses

{"platform":"Twitch","user":"xqc","isLive":true,"title":"Gaming","viewerCount":50000}

Use Cases

• Sending a Discord notification when a Twitch streamer goes live with viewer count
• Building a multi-platform live status dashboard that shows which streamers are currently broadcasting

Parameters

Responses

{"platform":"TikTok","user":"khaby.lame","isLive":false,"url":"https://www.tiktok.com/@khaby.lame/live"}

Use Cases

• Sending a Discord notification when a TikTok creator starts a live stream
• Monitoring TikTok live status without needing API credentials

Prerequisites

• Premium subscription for the guild
• Bot with Administrator permission (or specific read permissions for all data types)

Required Headers

Responses

{"status":"New backup created successfully","viewId":"123-abc","authKey":"base64key","fileSize":"2.5 MB"}

{"error":"Backups are a premium feature."}

{"error":"Backup too large (> 100 MB)"}

Use Cases

• Creating a full server backup before making major structural changes (role reorganization, channel cleanup)
• Scheduled automated backups for disaster recovery with the auth key stored securely for future updates
• Migrating server configuration to a new server by backing up and restoring

Related Endpoints

• Restore Backup — complementary

Prerequisites

• Premium subscription required
• Valid auth key

Required Headers

Parameters

Responses

{"error":"Backup not found or invalid key"}

Use Cases

• Downloading a backup file for offline storage or manual inspection of server configuration
• Exporting server structure data for documentation or migration planning

Prerequisites

• Premium subscription required
• Valid auth key

Required Headers

Parameters

Responses

{"status":"Deleted"}

Use Cases

• Removing outdated backups to free storage space
• Deleting a backup after a successful restore to prevent stale data from being accidentally restored later

Prerequisites

• Premium subscription for the guild
• Bot with Administrator permission
• ?force=true query parameter to confirm destructive action
• 5-minute cooldown between restore attempts for the same guild

Required Headers

Parameters

Responses

{"status":"Restore sequence finished","report":["Roles restored","Channels restored"]}

{"error":"Append ?force=true to confirm."}

{"error":"Cooldown active.","retryAfterSeconds":180}

Use Cases

• Restoring a server to a known-good state after accidental mass-deletion of channels or roles
• Migrating a server's complete structure (roles, channels, permissions) to a new guild using backup/restore
• Disaster recovery after a compromised admin account deleted server infrastructure

Related Endpoints

• Create Backup — complementary