The MumbleMe API

Read and manage your own Mumble servers from your own scripts, bots and dashboards: who’s on, the channel tree, permissions, moderation. Changes that matter wait for your approval.

What it is

A JSON-over-HTTPS API with an API key you create in your dashboard. It offers exactly what AI app connections offer, through the same code and the same checks: one endpoint for each of their tools, the same permissions, limits, approvals and undo. Use whichever suits you, or both.

Every endpoint is under this address:

API keys

1. In your dashboard, open API keys (in your account menu).
2. Name the key after what will use it, tick the servers it may see, and tick any kinds of change it may make. Reading is always included; changes are off unless you tick them.
3. Choose how long it works (30, 90, 365 days), and create it.
4. Copy the key, which starts mmk_. It is shown once: MumbleMe stores only a hash of it, so it can’t be shown again. Keep it out of code you share.

MumbleMe emails you when a key is created. The API keys page lists each key, its servers, what it may do and when it was last used. Revoke stops it at once and cancels changes it asked for that haven’t run yet. To change a key’s servers or permissions, create a new key and revoke the old one. Operator accounts can’t have keys.

Your first request

Send the key as a bearer token. GET /servers lists the servers the key may see; each server value is what the other endpoints take.

curl "https://mumbleme.com/api/v1/servers" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

Every answer is JSON and names the account the key belongs to (partly masked) in account. Lists come in pages of up to 100: when complete is false, send next_cursor back as cursor. A channel is named by its path (/ is the top level, /Raids/Wednesday two below it), passed as channel. A connected person is named by the user value from GET /servers/{server}/users, which stops working once they disconnect.

Making changes

• Idempotency-Key header, required. Send a new unique value (a UUID) with every change you mean to make, and the same value again only to retry the same request: a retry returns the first answer, with duplicate: true, instead of acting twice. The same key with different contents is refused (idempotency_conflict).
• Stale-write protection. Changing a description needs the description_version you read it with, and a permission proposal the permissions_version; if it changed meanwhile, the request is refused (409 stale). Read it again and retry.
• The answer is the change. 200 when it has finished: check status (succeeded or failed, with error). 202 when it hasn’t yet: queued, or waiting for your approval. Follow it with GET /operations/{operation}.
• Undo. App and API changes in your dashboard lists every change your keys and apps asked for: delete a created channel, restore a description or permissions, remove a ban. Each change also appears in the server’s Activity, marked with the key’s name.

Approving changes

Permission and group changes, private channels, bans, unbans and actions on several people at once answer 202 with status: awaiting_approval and an approval_url. Open it signed in to MumbleMe to see exactly what would change and approve or reject it. It lapses after 30 minutes, and isn’t applied if what it was based on has changed. No API call can approve a change: that always takes you, in the dashboard.

Errors

A refusal is JSON: {"error": {"code": "…", "message": "…"}}. The message is a sentence for a person; the code is stable and safe to branch on.

Limits

• Per key: 120 requests and 20 changes a minute.
• Channels can be created while a server has fewer than 250, at most 25 a day per key.
• Channels, connected people and bans can only be read while the server is running.
• No CORS: the API is for your own scripts and servers, not for web pages in a browser.

Endpoint reference

Every endpoint, generated from the definitions the API itself runs. A key sees only what its permissions allow.

curl "https://mumbleme.com/api/v1/servers" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

curl "https://mumbleme.com/api/v1/servers/$SERVER" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

curl "https://mumbleme.com/api/v1/servers/$SERVER/users" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

curl "https://mumbleme.com/api/v1/servers/$SERVER/registered-users" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

curl "https://mumbleme.com/api/v1/servers/$SERVER/channels" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

curl "https://mumbleme.com/api/v1/servers/$SERVER/channel?channel=%2FRaids" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

curl "https://mumbleme.com/api/v1/servers/$SERVER/channel/permissions?channel=%2FRaids" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

curl "https://mumbleme.com/api/v1/servers/$SERVER/users/$USER/permissions?channel=%2FRaids" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

curl "https://mumbleme.com/api/v1/servers/$SERVER/bans" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

curl "https://mumbleme.com/api/v1/operations/$OPERATION" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY"

curl -X POST "https://mumbleme.com/api/v1/servers/$SERVER/channels" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"parent":"/","name":"Raids","description":"Wednesday raids, 8pm."}'

curl -X PUT "https://mumbleme.com/api/v1/servers/$SERVER/channel/description" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"channel":"/Raids","description":"Wednesday raids, 8pm.","description_version":"…"}'

curl -X POST "https://mumbleme.com/api/v1/servers/$SERVER/channel/permissions" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"channel":"/Raids","permissions_version":"…","inherit":true,"rules":[],"groups":[]}'

curl -X POST "https://mumbleme.com/api/v1/servers/$SERVER/private-channels" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"parent":"/","name":"Raids","members":["alice"],"description":"Wednesday raids, 8pm."}'

curl -X POST "https://mumbleme.com/api/v1/servers/$SERVER/private-channels/access" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"channel":"/Raids","grant":["alice"],"revoke":[],"permissions_version":"…"}'

curl -X POST "https://mumbleme.com/api/v1/servers/$SERVER/users/$USER/move" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"channel":"/Raids"}'

curl -X PUT "https://mumbleme.com/api/v1/servers/$SERVER/users/$USER/mute" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"muted":true}'

curl -X PUT "https://mumbleme.com/api/v1/servers/$SERVER/users/$USER/deafen" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"deafened":true}'

curl -X POST "https://mumbleme.com/api/v1/servers/$SERVER/users/$USER/kick" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Please keep it civil."}'

curl -X POST "https://mumbleme.com/api/v1/servers/$SERVER/users/$USER/ban" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Please keep it civil.","duration_hours":24}'

curl -X DELETE "https://mumbleme.com/api/v1/servers/$SERVER/bans/$BAN" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

curl -X POST "https://mumbleme.com/api/v1/servers/$SERVER/moderation" \
  -H "Authorization: Bearer $MUMBLEME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"action":"move","users":["u12.1730000000.…","u15.1730000000.…"],"channel":"/Raids","reason":"Please keep it civil."}'

OpenAPI

The whole API as an OpenAPI 3.1 document, generated from the same definitions, for client generators and API tools:

Privacy

The API answers your key with what it may see on the servers you chose: server and channel names, descriptions, the names people use, registered member names, who is connected and where, permissions, groups, ban names and reasons. Where it goes next is up to your tools. Never sent: IP addresses, certificates and their fingerprints, members’ email addresses and comments, passwords and your billing. MumbleMe keeps a record of each key and of every change it asks for. See the Privacy Policy.

Versions

This is version 1 (/api/v1). Within it, MumbleMe may add endpoints, optional inputs and answer fields, so ignore fields you don’t know. Anything that would break a working script comes as a new version, with notice. Questions or problems: contact support, saying which key (its name, never the key itself) and roughly when.