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. Server endpoints need an API key; badge endpoints are public.

Base URL

https://redmumble.eu

Quick start

Authentication

All /api/v1/* endpoints require an API key. Generate one under Settings → Advanced → API, badges and webhooks in 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), 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 the 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 is 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 needed. Every badge needs the serverId query parameter (the badge server ID shown in your dashboard), and badges must be turned on under Settings → Advanced. Responses are cached for 5 minutes (Cache-Control: public, max-age=300).

Markdown example (GitHub README)

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

Shields.io response

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

BBCode example (forum signature)

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

Rate limits and errors

All /api/v1/* responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix timestamp).

429 response

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

Webhooks

Webhooks send real-time server events to an HTTPS endpoint you control. When something happens, RedMumble POSTs a signed JSON payload to your URL within seconds.

Register a webhook under Settings → Advanced → API, badges and webhooks in your dashboard. Pick which events you want and copy the signing secret, which is shown once.

Envelope

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

Event types

User event fields

• session: Murmur’s per-connection id. Use it to match a connect with its disconnect. New on every reconnect.
• userId: the user’s registered id on your server, or -1 if they haven’t registered.
• userName: the name the user chose in their Mumble client.

Verifying the signature

Every delivery has an X-Webhook-Signature header with sha256=<hex>: an HMAC-SHA256 of the raw body using your webhook secret (a 64-character hex string). Always verify it before processing.

curl / openssl

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

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

C#

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

bool VerifyWebhookSignature(string secretHex, byte[] requestBody, string signatureHeader)
{
    var secretBytes = Convert.FromHexString(secretHex);
    using var hmac  = new HMACSHA256(secretBytes);
    var expected    = "sha256=" + Convert.ToHexString(hmac.ComputeHash(requestBody)).ToLowerInvariant();
    // Timing-safe comparison
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(signatureHeader));
}

Retries

After 4 attempts the delivery is marked failed; you can retrigger it from the delivery history in your dashboard. Your endpoint must respond within 10 seconds with any 2xx status.