Noctra Public API

Record a new moderation action (warn, timeout, ban, kick, unban) for a Discord user.

Records a moderation action and generates a viewable HTML moderation log page stored in S3. The bot token is validated live against the Discord API (GET /users/@me) to ensure the bot is a member of the target guild. User and guild metadata (avatars, names, icons) are resolved via parallel Discord API calls. The response includes a permanent viewUrl that renders a styled HTML page with dark/light mode, search, and filtering. S3 path: {bucket}/{botId}/{guildId}/{userId}.json.

Permanently bans a user from a Discord server.

Executes a permanent ban via the Discord API (PUT /guilds/{serverId}/bans/{userId}). The ban is immediate and the user cannot rejoin until unbanned. The reason 'Banned via API' is recorded in the Discord audit log. Returns the banned user ID and server ID on success. Requires the bot to have BAN_MEMBERS permission and a role higher than the target user in the hierarchy.

Bans a user with a custom reason and optional message deletion period.

Executes a ban with extended options via a JSON body. The reason is recorded in the Discord audit log (X-Audit-Log-Reason header). The deleteMessageDays parameter (0-7) controls how many days of the user's messages are purged from the server. Internally converts deleteMessageDays to delete_message_seconds for the Discord API v10 endpoint.

Removes a ban from a user on a Discord server.

Revokes an active ban via the Discord API (DELETE /guilds/{serverId}/bans/{userId}). After unbanning, the user can rejoin the server if they have a valid invite link. The action is recorded in the Discord audit log.

Kicks a user from a Discord server.

Removes the user from the server via the Discord API (DELETE /guilds/{serverId}/members/{userId}). Unlike a ban, the user can rejoin immediately if they have a valid invite link. An optional reason is recorded in the Discord audit log via the X-Audit-Log-Reason header. Returns 204 No Content from Discord on success.

Applies a communication timeout to a user on a Discord server.

Temporarily prevents a user from sending messages, reacting, or joining voice channels. Duration is specified via the 'duration' header using a numeric value followed by a unit suffix: m (minutes), h (hours), d (days), w (weeks). Maximum allowed duration is 28 days. The timeout expiration timestamp (ISO 8601) is returned in the response. Requires MODERATE_MEMBERS permission.

Removes an active timeout from a user before it expires.

Removes an active communication timeout by setting communication_disabled_until to null via the Discord API (PATCH /guilds/{serverId}/members/{userId}). The user immediately regains the ability to send messages, react, and join voice. Requires MODERATE_MEMBERS permission. An optional reason is recorded in the audit log.

Forwards a user's Direct Message to the designated staff modmail channel.

Acts as a stateless bridge between a Discord bot and a staff channel. When a user sends a DM to the bot, this endpoint creates a rich embed in the staff channel containing the message content, sender info, and any attachments. The message body must be sent as raw plain text (Content-Type: text/plain). Multiple attachments are supported via the X-Attachment-Url header (semicolon-separated URLs, up to 10 images rendered as a gallery).

Sends a staff reply to a user via Direct Message.

Sends a formatted embed DM to the specified user as a reply from staff. The reply content must be sent as raw plain text (Content-Type: text/plain). The bot appears as the sender of the DM. Multiple attachments are supported via the X-Attachment-Url header (semicolon-separated). Will fail if the user has DMs disabled or does not share a server with the bot.

Retrieves detailed metadata about a specific Discord channel.

Fetches comprehensive channel information from the Discord REST API (v10) including channel name, type (text, voice, forum, etc.), topic, position within the channel list, permission overwrites for roles and members, rate limit (slow mode) settings, NSFW flag status, and parent category. The bot token prefix is added internally. Subject to Discord API rate limits.

Moves a Discord channel to a different category and/or changes its position.

Performs a channel move with intelligent reordering. When a target category is specified, the channel is moved into that category and inserted at the given position index (0-based) among channels of the same type. All sibling channels are automatically reordered to maintain consistent sequential positions. When no target category is specified, only the channel's position value is updated. The position is clamped to valid bounds (0 to channel count).

Retrieves available additional perks for a Discord guild based on boost status.

Analyzes a Discord server's boost status using official Discord API Guild Features to detect currently active additional perks. Returns detection status for Server Tags (GUILD_TAGS feature flag) and Enhanced Role Styles (ENHANCED_ROLE_COLORS feature flag). Some newer features like Server Tag Badge Packs do not yet have dedicated API feature flags and cannot be detected. Even with sufficient boosts, some features may not be available due to Discord's gradual rollout process.

Retrieves available booster role customization privileges for a guild.

Determines which booster role customization options are available based on the guild's premium tier and feature flags. Returns privilege levels: Standard (always available), Color (Tier 1+, 2 boosts), Gradient (Tier 2+, 7 boosts, requires ENHANCED_ROLE_COLORS), and Icon (Tier 2+, 7 boosts, requires ROLE_ICONS). Each privilege includes required tier, required boosts, and whether it is currently available.

Retrieves keyword filters from enabled auto moderation rules for a Discord guild.

Fetches all auto moderation rules from the Discord API, filters to only enabled rules, and extracts keyword_filter entries from their trigger_metadata. Returns the total count of keywords and a comma-separated string of all keyword filter entries. Rate limited to 1 request per minute per bot token to prevent excessive Discord API calls. Requires MANAGE_GUILD permission.

Retrieves detailed information about a Discord category and all channels within it.

Fetches a Discord category channel by ID and returns comprehensive information including all child channels with their settings, permissions, and metadata. The response includes total channel count, category position, guild info, and per-channel details (type, topic, NSFW flag, slow mode, bitrate, user limit, permission overwrites). Channel creation timestamps are derived from Discord snowflake IDs.

Retrieves comprehensive real-time voice channel information including connected users.

Establishes a temporary Discord Gateway WebSocket connection to fetch live voice channel data. Returns channel details (name, bitrate, user limit, region, category, position) and a list of all currently connected users with their voice states (muted, deafened, streaming, camera). Uses GUILDS and GUILD_VOICE_STATES intents. Note: The Gateway connection takes approximately 3 seconds to initialize and receive voice state data.

Creates a new role in a Discord guild with full customization options.

Creates a role via the Discord API with support for name, solid color, gradient colors (2-3 hex values for gradient/holographic effects), permissions, hoist, mentionable, icon (downloaded from URL and converted to Base64), and position. Supports Discord's ENHANCED_ROLE_COLORS feature with automatic fallback — if the guild doesn't have the feature, the 'colors' object is removed and only the legacy color field is used. The guild is validated via the Discord API before creation.

Creates a personalized custom booster role for a server booster.

Creates a custom role exclusively for a verified server booster. Validates that the user is a member of the guild, has the booster role, and doesn't already have a custom booster role (limit 1 per user). The role is automatically positioned above the server's booster role in the hierarchy and assigned to the user. Supports custom name, color, gradient colors, and icon.

Updates an existing custom booster role.

Updates name, color, gradient, or icon of a user's custom booster role.

Permanently deletes a user's custom booster role from the guild.

Validates that the requesting user owns the specified role before deleting it via the Discord API (DELETE /guilds/{guildId}/roles/{roleId}). The role is permanently removed from the guild and all members who had it assigned.

Removes all members from a specified Discord role (max 50 per request).

Fetches all guild members via paginated API calls, identifies those with the specified role, and removes the role from up to 50 members per request. Includes retry logic (up to 3 attempts per member) with exponential backoff for rate limiting. Uses progressive delays between removals (200ms increasing to 1s) to avoid Discord API rate limits. Automatically discovers the guild ID by searching through the bot's guilds for the target role.

Retrieves the highest-positioned role assigned to a specific user in a Discord guild.

Proxies the request to the Noctra v2 API to determine a user's highest role by position value. The highest role determines the user's effective permission level in the role hierarchy — a higher position number means more authority. The Discord bot token is forwarded as an Authorization header. Returns the role name or position data.

Retrieves the number of members assigned to a specific role in a Discord guild.

Proxies the request to the Noctra v2 API to count how many users have a specific role assigned. The Discord bot token is forwarded as an Authorization header to the external API. Returns the count as a plain number. Useful for displaying role statistics in dashboards or monitoring role assignment growth over time.

Retrieves Discord guild members filtered by one or more role IDs via Gateway WebSocket.

Establishes a WebSocket connection to the Discord Gateway to fetch all guild members, then filters by the specified role IDs. Supports two modes: 'all' (members must have ALL specified roles) and 'any' (members with at least one role). The 'duplications' header controls whether a user with multiple matching roles appears once (assigned to their highest role) or multiple times. Uses GUILD_MEMBERS intent. Should be used sparingly as repeated calls count as WebSocket spam. Overall timeout: 180 seconds.

Sends a formatted embed message to a Discord channel with rate limiting.

Posts an embedded message to a Discord channel with customizable title, description, color (integer), optional footer with icon, optional large image, and optional plain text content outside the embed. Includes per-channel rate limiting (10-second cooldown) to prevent spam. The bot must have SEND_MESSAGES and EMBED_LINKS permissions in the target channel. Returns HTTP 429 with remaining cooldown time if rate limit is exceeded.

Updates a single component within a Discord message using content-based search.

Uses a 'Search and Replace' approach to find a component by a unique substring of its text content (whitespace- and case-insensitive comparison). Retrieves the current message state via GET, locates the matching component, replaces its entire 'content' field with the new value, and PATCHes the message back. Returns 404 if no match is found, or 409 if the search text matches multiple components (ambiguity). Only writable fields (content, embeds, components, allowed_mentions) are sent in the PATCH payload.

Updates a component in an ephemeral (hidden) Discord message using smart search.

Identical smart edit logic as the main endpoint, but specifically for ephemeral messages tied to a Discord interaction. Uses the bot's Application ID and the Interaction Token (valid for 15 minutes after the interaction) instead of Channel/Message IDs. The search for targetContentSubstring is whitespace- and case-insensitive. Channel and Message IDs are not needed since ephemeral messages are addressed via the webhook URL pattern.

Checks if a Discord message contains a file attachment and identifies the file type.

Inspects a specific Discord message via the Discord API to detect file attachments (direct uploads) and embedded media (link previews from imgur, giphy, etc.). Detection uses a priority chain: first checks the attachments array for content_type, then filename extension, then URL; then checks embeds for image/video/gifv types. Supports images (png, jpg, gif, webp), videos (mp4, webm, mov), documents (pdf, docx), and archives (zip, rar). Returns isFile (boolean) and fileType (string or null).

Returns the account age of a Discord user.

Calculates account age from the Discord snowflake ID. Returns age in days, weeks, months, and years. Useful for age-gating, anti-raid detection, and trust scoring.

Compares permission levels and role hierarchies of two Discord users within a guild.

Performs a comprehensive permission comparison using the Discord REST API. Evaluates each user's effective permissions by aggregating all assigned roles, considering role hierarchy (position value), and checking for special permissions like Administrator and server ownership. Returns highest role position, owner status, and which user has higher authority. Server owners always have maximum authority regardless of roles.

Compares a user's highest role position against multiple specified roles.

Checks if a user's highest role is above each of the provided roles (comma-separated IDs). Roles are numbered from left to right (1-indexed) in the order provided. Uses Discord role position values for comparison — higher position number means higher authority. Server owners are automatically considered higher than all roles. Returns per-role comparison results and an overall summary.

Retrieves basic guild information including name, owner, and member count.

Returns fundamental guild metadata via the Discord REST API including guild ID, name, owner ID, approximate member count, and creation date. Uses the bot's cached guild data. Useful for quick server overview without fetching detailed channel or role information.

Resolves a Discord invite link or code into structured server and inviter data.

Queries the Discord API (GET /invites/{code}?with_counts=true&with_expiration=true) to retrieve detailed invite metadata. Accepts full URLs (discord.gg/..., discord.com/invite/...) or bare invite codes. Returns guild information (name, ID, icon, vanity URL, description), target channel (name, ID, type), inviter profile (username, ID, avatar, bot status), and approximate member/presence counts.

Generates a self-contained HTML transcript of a Discord channel and uploads it to S3.

Fetches up to 10,000 messages from a Discord channel via the REST API, embeds all media (images, videos up to 600 MB, audio) as Base64 data-URIs into a single self-contained HTML file, uploads it to S3-compatible storage, writes a JSON index entry for metadata, and optionally posts the transcript file to a target Discord channel. Returns a direct view-link and the view ID. The HTML file is fully self-contained with no external dependencies.

Retrieves a paginated list of all transcripts for a specific guild from S3 storage.

Lists all transcript index files from S3, filters by the requested guild ID, reads metadata (channel name, creator info, timestamps), determines file sizes via HEAD requests, and returns results sorted by creation date (newest first). Supports role-based access control — admin-only transcripts (channels with 'admin' in the name) are hidden from moderator-level users. Session-based authentication is used when available.

Returns the HTML content of a previously stored transcript.

Retrieves a transcript by its unique GUID and returns it as self-contained HTML. Browser requests (with Accept: text/html) are automatically redirected to the dashboard viewer at /dashboard/transcript/{id}. To bypass the redirect and receive the raw HTML directly, append ?embed=true as a query parameter. Bot and programmatic clients (without Accept: text/html header) always receive the raw HTML without needing the embed parameter. Requires session-based authentication (at least moderator level). Admin-only transcripts (from channels with 'admin' in the name) require administrator permissions.

Accepts plain text and returns it as a JSON-safe escaped string.

Requires Content-Type: text/plain. Manually escapes all special characters (backslashes first to avoid double-escaping, then quotes, newlines, carriage returns, and tabs) so the result can be safely embedded in a JSON template string without breaking structure. Returns the original text, character count, and the escaped version.

Splits large text into Discord-safe message chunks at word boundaries.

Splits text at word boundaries (spaces) to avoid breaking words mid-character. Default chunk size is 1800 characters (leaves buffer for Discord formatting/embeds). If a single word exceeds the chunk size, it is placed in its own chunk. Returns indexed chunks with content, length, total chunks, total characters, and the chunk size used.

Tests a regular expression pattern against an input string with timeout protection.

Evaluates a .NET regex pattern against a provided string with a 1-second timeout to prevent ReDoS (Regular Expression Denial of Service) attacks. Case sensitivity is controlled via the X-Regex-Case-Sensitive header (defaults to case-sensitive). Returns whether the input matched, the matched substring (if any), and error details on failure. Supports standard .NET Regex syntax.

Generates a Discord-compatible Unix timestamp based on a time offset from now.

Calculates a future (or present) Unix timestamp by adding a specified duration to the current UTC time. Supports units: seconds, minutes, hours, days, and 'now' (returns current timestamp). The returned value can be used in Discord messages with the format <t:TIMESTAMP:R> for relative time or <t:TIMESTAMP:F> for full date/time display.

Compares two string lists and returns their intersection (common values).

Performs a set intersection operation on two provided string arrays and returns the common values. Useful for Discord bot operations such as finding shared roles between two users, identifying common permissions across role sets, or comparing channel access lists. Rate limiting is configured per client IP address (currently set to 0-second cooldown, effectively disabled).

Generates a fully customizable Discord-style level/rank card image and uploads it to S3.

All configuration is passed via HTTP Headers. Renders a rank card using SkiaSharp with support for username, avatar, level, XP (with automatic percentage calculation), rank position, voice time, message count, activity count, custom background (image or solid color with opacity/blur), gradient progress bar, custom colors for all elements, font selection, and precise X/Y offset positioning for every component. Uploads the generated PNG to S3 and returns both a direct view URL and Base64 image data. Avatar URLs must be from allowed domains.

Generates a fully customizable Discord-style welcome card and uploads it to S3.

All configuration is passed via HTTP Headers. Renders a welcome card image using SkiaSharp with support for custom background images, user avatars (circle or rounded rect), greeting text, guild name, member count, full color customization, font selection, and precise X/Y positioning of all elements. Emojis are automatically stripped from text fields. Supports Base64 or double URL-encoding for special characters in headers. Uploads the generated PNG to S3 and returns a direct view URL.

Retrieves the list of available font families for card generation.

Returns a JSON list of all supported font keys and their display names that can be used in the Typography-Family header for both welcome cards and level cards. Includes system fonts like Arial, Verdana, Georgia, Segoe UI, and others.

Provides text encoding and emoji handling documentation for card generation.

Returns the encoding guide including API version, supported encoding methods (Base64 recommended, double URL-encoding as fallback), allowed image domains, and a note that emojis are automatically stripped from all text fields. Useful for understanding how to properly encode special characters in HTTP headers.

Checks live streaming status across YouTube, Twitch, and TikTok simultaneously.

Performs parallel live status checks across all specified platforms. Platforms with empty handles or the literal value 'none' are skipped and excluded from the response. YouTube uses the Data API v3 (100 quota units per check, cached 15 minutes). Twitch uses Client Credentials OAuth flow (token cached until expiry). TikTok uses a static availability check with no API key required. API keys can be provided via headers or server configuration (config takes priority).

Checks if a YouTube channel is currently live streaming.

Resolves a YouTube handle to a channel ID (1 quota unit, cached 30 days), then checks for active live streams via search.list (100 quota units, cached 15 minutes). Returns live status, stream title, and direct URL. Pass 'none' as the handle to skip without making any API call. API key can be provided via header or server configuration.

Checks if a Twitch channel is currently live streaming.

Automatically obtains an App Access Token using the Client Credentials OAuth flow (credentials sent via POST body, not URL). The token is cached server-side using the actual expires_in value from Twitch (minus 5-minute buffer). Checks the Helix streams endpoint for the specified user. Returns live status, stream title, viewer count, and channel URL. Results cached for 60 seconds.

Checks if a TikTok user is currently live streaming.

Uses TikTokLiveClient.GetUserStreaming() for a lightweight static availability check — no API key required and no WebSocket overhead. Results are cached for 2 minutes. Pass 'none' as the username to skip without making any check. Returns live status and direct link to the user's live page.

Creates a new server backup or updates an existing one. (Premium)

Fetches all relevant Discord server data (roles, channels, AutoMod rules, onboarding config, bans) via Discord API v10 and stores it as a JSON file in S3. Uses a stateless, secure architecture with HMAC-SHA256 signatures embedded in S3 filenames for ownership verification. If X-Auth-Key matches an existing backup, the file is updated in-place; otherwise a new backup is created with fresh credentials. Enforces a one-backup-per-guild rule. Maximum backup size: 100 MB. Premium-only feature.

Downloads a backup file as a JSON attachment. (Premium)

Retrieves the raw JSON backup file from S3 as a downloadable attachment. The auth key is verified using timing-safe HMAC comparison against the key embedded in the S3 filename. Returns Content-Disposition: attachment header for browser download.

Permanently deletes a backup from S3 storage. (Premium)

Permanently removes the backup JSON file from S3 after verifying the auth key via timing-safe HMAC comparison. This action is irreversible — the backup data cannot be recovered after deletion.

⚠️ DESTRUCTIVE: Restores a Discord server from a backup. (Premium)

WARNING: This action deletes existing roles, channels, and AutoMod rules before recreating them from the backup data. The restore process tracks old IDs vs. new IDs in memory to correctly map permissions, channels, and roles during recreation. Safety measures: requires ?force=true query parameter to execute, enforces a 5-minute cooldown per guild ID, and requires both a valid auth key and a bot token with Administrator permissions. The restore sequence runs: Roles → Channels → AutoMod → Onboarding, with each step reported independently. Premium-only feature.