Developer API

API Overview

The RedMumble API lets you query your Mumble server state, embed live status badges in READMEs and community sites, and build bots and integrations. Authentication is required for server endpoints; badge endpoints are public.

Base URL:

https://redmumble.eu

Quick Start

Authentication

All /api/v1/* endpoints require an API key. Generate one from the Advanced section of your dashboard.

# Bearer header (preferred)
curl -H "Authorization: Bearer YOUR_API_KEY" https://redmumble.eu/api/v1/server

# Query parameter (alternative)
curl "https://redmumble.eu/api/v1/server?key=YOUR_API_KEY"

Server API

GET /api/v1/server

Cached 15s. Returns current server status.

curl -H "Authorization: Bearer YOUR_API_KEY" https://redmumble.eu/api/v1/server

Response (200):

{
  "id": 3,
  "name": "MyServer",
  "isRunning": true,
  "connectedUsers": 4,
  "maxUsers": "15",
  "uptimeSeconds": 86400,
  "welcomeText": "Welcome!"
}

Errors: 401 Unauthorized, 503 server unreachable.

GET /api/v1/server/users

Cached 10s. Returns connected users.

curl -H "Authorization: Bearer YOUR_API_KEY" https://redmumble.eu/api/v1/server/users

Response (200) — abbreviated (one item shown):

[
  {
    "session": 1,
    "name": "Alice",
    "channelId": 0,
    "channelName": "Root",
    "onlineSeconds": 1234,
    "selfMute": false,
    "selfDeaf": false
  }
]

Errors: 401 Unauthorized, 503 server unreachable.

GET /api/v1/server/channels

Cached 60s. Returns channel list.

curl -H "Authorization: Bearer YOUR_API_KEY" https://redmumble.eu/api/v1/server/channels

Response (200) — abbreviated:

[
  {
    "id": 0,
    "name": "Root",
    "parentId": -1,
    "description": ""
  }
]

Errors: 401 Unauthorized, 503 server unreachable.

POST /api/v1/server/message

Broadcasts a text message to all connected users. message field required, max 1000 characters.

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d "{\"message\":\"Hello from the API!\"}" \
     https://redmumble.eu/api/v1/server/message

Response: 204 No Content on success.

Errors: 400 validation error (message empty or over 1000 chars), 401 Unauthorized, 503 server unreachable.

Badge API

Badge endpoints are public — no API key required. All badge endpoints require a serverId query param (the badge server ID shown in your dashboard). BadgesEnabled must be turned on for your server from the Dashboard. Responses are cached with Cache-Control: public, max-age=300 (5 minutes).

GitHub README & Markdown (SVG)

SVG badges render inline on GitHub. Use the Markdown embed code directly in your README.

GET /api/badge/status

SVG badge showing MUMBLE | ONLINE or MUMBLE | OFFLINE.

curl "https://redmumble.eu/api/badge/status?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Markdown embed:

![Mumble Status](https://redmumble.eu/api/badge/status?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

GET /api/badge/players

SVG badge showing ONLINE | N/M player count.

curl "https://redmumble.eu/api/badge/players?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Markdown embed:

![Mumble Players](https://redmumble.eu/api/badge/players?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

GET /api/badge/shields

Shields.io JSON endpoint. Paste this URL into a Shields.io endpoint badge for full style customisation.

curl "https://redmumble.eu/api/badge/shields?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Response:

{
  "schemaVersion": 1,
  "label": "mumble",
  "message": "4/15 players",
  "color": "brightgreen"
}

Reddit & platforms that block external SVGs (PNG, 2×)

Reddit and many community platforms refuse to render externally-hosted SVGs inline. Use the PNG variants instead — they are pre-rasterised at 2× scale so they stay crisp.

GET /api/badge/status.png

Status badge rendered as a PNG at 2× scale (60 px tall).

curl "https://redmumble.eu/api/badge/status.png?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Markdown embed (Reddit, Discord):

![Mumble Status](https://redmumble.eu/api/badge/status.png?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

GET /api/badge/players.png

Players badge rendered as a PNG at 2× scale.

curl "https://redmumble.eu/api/badge/players.png?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Markdown embed:

![Mumble Players](https://redmumble.eu/api/badge/players.png?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Forum signatures (HTML / BBCode)

Classic forum signature formats. SVG versions work on forums that allow external images; use the PNG variants on forums that block SVGs.

GET /api/badge/userbar

350×19 pixel-font SVG userbar.

curl "https://redmumble.eu/api/badge/userbar?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

HTML embed:

<img src="https://redmumble.eu/api/badge/userbar?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" alt="Mumble Userbar">

BBCode embed:

[img]https://redmumble.eu/api/badge/userbar?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx[/img]

GET /api/badge/userbar.png

Same userbar rendered as a PNG (350×19). Use on forums that block SVGs.

curl "https://redmumble.eu/api/badge/userbar.png?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

HTML embed:

<img src="https://redmumble.eu/api/badge/userbar.png?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" alt="Mumble Userbar">

BBCode embed:

[img]https://redmumble.eu/api/badge/userbar.png?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx[/img]

GET /api/badge/banner

468×60 SVG forum signature banner.

curl "https://redmumble.eu/api/badge/banner?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

HTML embed:

<img src="https://redmumble.eu/api/badge/banner?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" alt="Mumble Banner">

BBCode embed:

[img]https://redmumble.eu/api/badge/banner?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx[/img]

GET /api/badge/banner.png

Same banner rendered as a PNG (468×60). Use on forums that block SVGs.

curl "https://redmumble.eu/api/badge/banner.png?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

HTML embed:

<img src="https://redmumble.eu/api/badge/banner.png?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" alt="Mumble Banner">

BBCode embed:

[img]https://redmumble.eu/api/badge/banner.png?serverId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx[/img]

Rate Limits and Errors

Rate Limits

Endpoint group	Limit	Window	Notes
`/api/v1/*`	6 req/min	Sliding window	Partitioned by API key
`/api/badge/*`	Exempt	—	Public, CDN-friendly

Rate Limit Headers

All /api/v1/* responses include these headers:

X-RateLimit-Limit: configured ceiling (e.g., 6)
X-RateLimit-Remaining: approximate requests remaining in current window
X-RateLimit-Reset: Unix timestamp of approximate window reset

429 response example:

{"error":"Rate limit exceeded. Please try again later."}

Common HTTP Status Codes

Status	Meaning
401	Missing or invalid API key
404	Server not found or badges not enabled
429	Rate limit exceeded
503	Murmur server unreachable

Webhooks

Webhooks allow your application to receive real-time Mumble server events at an HTTPS endpoint you control. When an event occurs on your server, RedMumble will POST a signed JSON payload to your registered URL within seconds.

Register a webhook from your Dashboard under Advanced → Webhooks. You select which event types to receive and get a signing secret shown once at registration time.

Envelope shape

All webhook POSTs send the following JSON body (camelCase). The payload object is event-specific — see the table below.

{
  "eventType":  "user.connected",
  "serverId":   "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "occurredAt": "2026-02-22T14:30:00.000Z",
  "payload":    { ... }
}

Event types & payloads

Event type	Description	Payload fields
`user.connected`	A user joined your Mumble server	`session`, `userId`, `userName`
`user.disconnected`	A user left your Mumble server	`session`, `userId`, `userName`
`message.sent`	A broadcast message was sent from the Dashboard	`session`, `userId`, `userName`, `text`
`channel.created`	A channel was created	`channelId`, `name`, `parentId`
`channel.deleted`	A channel was deleted	`channelId`, `name`
`channel.renamed`	A channel was renamed	`channelId`, `oldName`, `newName`
`server.config_updated`	Server name or welcome text was updated	`null`
`webhook.test`	Manual test event sent from the Dashboard	`null`

User event payload fields

Example for user.connected and user.disconnected:

{
  "eventType": "user.disconnected",
  "serverId":  "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "occurredAt": "2026-02-28T21:05:10.422Z",
  "payload": {
    "session":  2,
    "userId":   -1,
    "userName": "Alice"
  }
}

session — Murmur's ephemeral per-connection identifier. Unique within a server instance for the lifetime of that connection. Use it to correlate a user.connected and its matching user.disconnected event, even when two users share the same display name. A new session number is assigned on every reconnect.
userId — Murmur's registered user ID. This is always -1 on RedMumble because Mumble users connect anonymously without registering an account on the Murmur server. A positive value would only appear if a user had registered via the Mumble client, which RedMumble does not require or support.
userName — the display name the user chose in their Mumble client.

Verifying the signature

Every delivery includes an X-Webhook-Signature header containing sha256=<hex> — an HMAC-SHA256 of the raw request body using your webhook secret. Always verify this header before processing the payload.

Your webhook secret is displayed as a 64-character hex string at registration time (and after rotation). Store it securely — it is not shown again.

curl / openssl example

SECRET="your-64-char-hex-secret"
BODY='{"eventType":"user.connected","serverId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","occurredAt":"2026-02-22T14:30:00Z","payload":null}'

# Compute expected signature
EXPECTED=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$(echo "$SECRET" | xxd -r -p)" -binary | xxd -p | tr -d '\n')
echo "sha256=$EXPECTED"

# Compare with the X-Webhook-Signature header value received on your endpoint

C# verification example

using System.Security.Cryptography;
using System.Text;

// secretHex: the 64-char hex string shown at registration
// requestBody: raw UTF-8 bytes of the HTTP request body
// signatureHeader: value of the X-Webhook-Signature header

bool VerifyWebhookSignature(string secretHex, byte[] requestBody, string signatureHeader)
{
    var secretBytes  = Convert.FromHexString(secretHex);
    var payloadBytes = requestBody;

    using var hmac = new HMACSHA256(secretBytes);
    var hashBytes  = hmac.ComputeHash(payloadBytes);
    var expected   = "sha256=" + Convert.ToHexString(hashBytes).ToLowerInvariant();

    // Use timing-safe comparison to prevent timing oracle attacks
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(signatureHeader));
}

Retry behavior

If your endpoint returns a non-2xx response or does not respond, RedMumble will retry the delivery automatically:

Attempt	Delay after previous attempt
1st attempt	Immediate
2nd attempt (retry 1)	5 seconds
3rd attempt (retry 2)	30 seconds
4th attempt (retry 3)	2 minutes

After 4 total attempts the delivery is marked failed. You can manually retrigger a failed delivery from the Delivery history section in your Dashboard.

Your endpoint must respond within 10 seconds per attempt. Respond with any 2xx status code to acknowledge receipt.

API Overview

Quick Start

Authentication

Server API

GET /api/v1/server

GET /api/v1/server/users

GET /api/v1/server/channels

POST /api/v1/server/message

Badge API

GitHub README & Markdown (SVG)

GET /api/badge/status

GET /api/badge/players

GET /api/badge/shields

Reddit & platforms that block external SVGs (PNG, 2×)

GET /api/badge/status.png

GET /api/badge/players.png

Forum signatures (HTML / BBCode)

GET /api/badge/userbar

GET /api/badge/userbar.png

GET /api/badge/banner

GET /api/badge/banner.png

Rate Limits and Errors

Rate Limits

Rate Limit Headers

Common HTTP Status Codes

Webhooks

Envelope shape

Event types & payloads

User event payload fields

Verifying the signature

Retry behavior

Connection lost