Mumboard API Documentation

Overview

The Mumboard API is a RESTful API that allows you to programmatically manage and play sounds in Mumble voice chat. All API endpoints require authentication via API keys.

Base URL

https://your-mumboard-instance.com/api/v1

API Versioning

The API is versioned using URL path versioning. Current version: v1

Response Format

All responses are returned in JSON format with the following structure:

{
  "success": true,
  "data": { ... }
}

Authentication

Generating an API Key

Log in to the Mumboard web interface
Navigate to Settings → API Keys
Click "Generate API Key"
Enter a name for your key (e.g., "My Application")
Optionally set an expiration date
Save the generated key securely - it will only be shown once!

Security Warning: Treat API keys like passwords. Never commit them to version control or share them publicly. If a key is compromised, deactivate or delete it immediately.

Using API Keys

Include your API key in every request using the HTTP header:

X-API-Key: mbk_your_api_key_here

Sounds API

GET /api/v1/sounds

Retrieve a list of all available sounds.

Headers

Name	Type	Required	Description
`X-API-Key`	string	Required	Your API key

Response

{
  "success": true,
  "count": 3,
  "sounds": [
    {
      "id": 1,
      "name": "Welcome",
      "filename": "1234567890-welcome.mp3",
      "tags": ["greeting", "intro"],
      "uploaded_by": "admin",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

GET /api/v1/sounds/:id

Retrieve details of a specific sound by ID.

URL Parameters

Name	Type	Description
`id`	integer	The sound ID

Response

{
  "success": true,
  "sound": {
    "id": 1,
    "name": "Welcome",
    "filename": "1234567890-welcome.mp3",
    "tags": ["greeting", "intro"],
    "uploaded_by": "admin",
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

GET /api/v1/sounds/search/by-tag

Search for sounds by tag.

Query Parameters

Name	Type	Required	Description
`tag`	string	Required	Tag to search for

Example Request

GET /api/v1/sounds/search/by-tag?tag=funny

Response

{
  "success": true,
  "tag": "funny",
  "count": 2,
  "sounds": [ ... ]
}

POST /api/v1/sounds

Upload a new sound file.

Headers

Name	Type	Description
`X-API-Key`	string	Your API key
`Content-Type`	string	multipart/form-data

Form Data

Name	Type	Required	Description
`sound`	file	Required	Audio file (MP3, WAV, OGG, M4A, FLAC). Max 10MB
`name`	string	Optional	Name for the sound. Defaults to filename
`tags`	string	Optional	Comma-separated tags (e.g., "funny,meme")

Response

{
  "success": true,
  "message": "Sound uploaded successfully",
  "sound": {
    "id": 42,
    "name": "Epic Sound",
    "filename": "1234567890-epic-sound.mp3",
    "tags": ["funny", "meme"],
    "uploaded_by": "api_user"
  }
}

PUT /api/v1/sounds/:id

Update sound metadata (name and tags).

Headers

Name	Type	Description
`X-API-Key`	string	Your API key
`Content-Type`	string	application/json

Request Body

{
  "name": "New Sound Name",
  "tags": "updated,tags,here"
}

Response

{
  "success": true,
  "message": "Sound updated successfully",
  "sound": {
    "id": 1,
    "name": "New Sound Name",
    "tags": ["updated", "tags", "here"]
  }
}

DELETE /api/v1/sounds/:id

Delete a sound permanently.

URL Parameters

Name	Type	Description
`id`	integer	The sound ID to delete

Response

{
  "success": true,
  "message": "Sound deleted successfully"
}

Playback API

POST /api/v1/sounds/:id/play

Play a sound in the Mumble channel.

Note: The bot must be connected to a Mumble server for this to work.

URL Parameters

Name	Type	Description
`id`	integer	The sound ID to play

Response

{
  "success": true,
  "message": "Sound is now playing",
  "sound": {
    "id": 1,
    "name": "Welcome"
  }
}

POST /api/v1/playback/stop

Stop all current playback.

Response

{
  "success": true,
  "message": "Playback stopped"
}

Mumble API

GET /api/v1/mumble/status

Get the current Mumble connection status.

Response

{
  "success": true,
  "status": {
    "connected": true,
    "currentChannel": "General"
  }
}

GET /api/v1/mumble/channels

Get a list of available channels on the Mumble server.

Response

{
  "success": true,
  "channels": [
    "Root",
    "General",
    "Gaming",
    "Music"
  ]
}

Code Examples

cURL

# Get all sounds
curl -X GET https://your-mumboard.com/api/v1/sounds \
  -H "X-API-Key: mbk_your_api_key_here"

# Upload a sound
curl -X POST https://your-mumboard.com/api/v1/sounds \
  -H "X-API-Key: mbk_your_api_key_here" \
  -F "sound=@/path/to/sound.mp3" \
  -F "name=My Sound" \
  -F "tags=funny,meme"

# Play a sound
curl -X POST https://your-mumboard.com/api/v1/sounds/1/play \
  -H "X-API-Key: mbk_your_api_key_here"

Python

import requests

API_BASE = "https://your-mumboard.com/api/v1"
API_KEY = "mbk_your_api_key_here"

headers = {
    "X-API-Key": API_KEY
}

# Get all sounds
response = requests.get(f"{API_BASE}/sounds", headers=headers)
sounds = response.json()["sounds"]

# Upload a sound
with open("sound.mp3", "rb") as f:
    files = {"sound": f}
    data = {
        "name": "My Sound",
        "tags": "funny,meme"
    }
    response = requests.post(
        f"{API_BASE}/sounds",
        headers=headers,
        files=files,
        data=data
    )

# Play a sound
response = requests.post(
    f"{API_BASE}/sounds/1/play",
    headers=headers
)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const API_BASE = 'https://your-mumboard.com/api/v1';
const API_KEY = 'mbk_your_api_key_here';

const headers = {
  'X-API-Key': API_KEY
};

// Get all sounds
async function getAllSounds() {
  const response = await axios.get(`${API_BASE}/sounds`, { headers });
  return response.data.sounds;
}

// Upload a sound
async function uploadSound(filePath, name, tags) {
  const form = new FormData();
  form.append('sound', fs.createReadStream(filePath));
  form.append('name', name);
  form.append('tags', tags);

  const response = await axios.post(`${API_BASE}/sounds`, form, {
    headers: {
      ...headers,
      ...form.getHeaders()
    }
  });
  return response.data;
}

// Play a sound
async function playSound(soundId) {
  const response = await axios.post(
    `${API_BASE}/sounds/${soundId}/play`,
    {},
    { headers }
  );
  return response.data;
}

JavaScript (Browser)

const API_BASE = 'https://your-mumboard.com/api/v1';
const API_KEY = 'mbk_your_api_key_here';

// Get all sounds
async function getAllSounds() {
  const response = await fetch(`${API_BASE}/sounds`, {
    headers: {
      'X-API-Key': API_KEY
    }
  });
  const data = await response.json();
  return data.sounds;
}

// Upload a sound
async function uploadSound(file, name, tags) {
  const formData = new FormData();
  formData.append('sound', file);
  formData.append('name', name);
  formData.append('tags', tags);

  const response = await fetch(`${API_BASE}/sounds`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY
    },
    body: formData
  });
  return await response.json();
}

// Play a sound
async function playSound(soundId) {
  const response = await fetch(`${API_BASE}/sounds/${soundId}/play`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY
    }
  });
  return await response.json();
}

Error Handling

HTTP Status Codes

Status Code	Description
`200`	Success
`201`	Created (successful upload)
`400`	Bad Request (invalid parameters)
`401`	Unauthorized (invalid or missing API key)
`404`	Not Found (sound doesn't exist)
`500`	Internal Server Error

Error Response Format

{
  "error": "Description of what went wrong"
}

Common Errors

Invalid API Key

// Status: 401
{
  "error": "Invalid or inactive API key"
}

Missing API Key

// Status: 401
{
  "error": "API key required. Provide via X-API-Key header"
}

Expired API Key

// Status: 401
{
  "error": "API key has expired"
}

Sound Not Found

// Status: 404
{
  "error": "Sound not found"
}

Bot Not Connected

// Status: 400
{
  "error": "Bot is not connected to Mumble server"
}

File Too Large

// Status: 400
{
  "error": "File too large. Maximum size is 10MB"
}

Invalid File Type

// Status: 400
{
  "error": "Only audio files are allowed. Supported formats: MP3, WAV, OGG, M4A, FLAC"
}

Rate Limiting

Currently, there are no rate limits enforced on the API. However, please be respectful of server resources:

Avoid making excessive concurrent requests
Implement reasonable delays between playback requests
Cache sound lists when possible instead of repeatedly fetching

Note: Rate limiting may be implemented in future versions if abuse occurs.

Support

For issues, questions, or feature requests:

Check the GitHub repository
Open an issue on GitHub
Contact your server administrator