Skip to main content

API Documentation

Integrate with MuteDeck using our local REST API for custom automation and control.

Overview​

The MuteDeck software has an open API that you can use to get the status of each button (mute, video, etc.) and control the buttons as well. This RESTful API is the way to integrate with MuteDeck and build something cool that reacts to or controls your meeting status. When the MuteDeck software is running, it runs a local web server where the API lives.

Interactive Documentation​

Live API Documentation

You can find the API endpoints and built-in documentation here: http://localhost:3491 (only works when MuteDeck is running)

There's also a built-in Swagger UI that can be used to test API calls and has the full API documentation.

Base URL​

When MuteDeck is running, the API is available at:

http://localhost:3491

Authentication​

No authentication is required for local API access.

Core Endpoints​

Get Status​

Get the current status of all meeting controls.

GET /v1/status

Example Response (No Meeting):

{
  "control": "system",
  "mute": "inactive",
  "record": "disabled",
  "share": "disabled",
  "status": 200,
  "video": "disabled"
}

Example Response (Active Zoom Meeting):

{
  "call": "active",
  "control": "zoom",
  "mute": "active",
  "record": "inactive",
  "share": "inactive",
  "status": 200,
  "video": "active"
}

Response Fields:

  • control: Which system is controlling ("system", "zoom", "teams", "meet", etc.)
  • call: Meeting status ("active" when in a meeting)
  • mute: Microphone status ("active" = muted, "inactive" = unmuted, "disabled")
  • video: Camera status ("active" = on, "inactive" = off, "disabled")
  • share: Screen share status ("active" = sharing, "inactive" = not sharing)
  • record: Recording status ("active" = recording, "inactive" = not recording)
  • status: HTTP status code (200 = success)

Toggle Mute​

Toggle the microphone on/off.

POST /v1/mute

Response:

{
  "status": 200,
  "action": "mute_toggle",
  "result": "active"
}

Toggle Video​

Toggle the camera on/off.

POST /v1/video

Toggle Screen Share​

Start/stop screen sharing.

POST /v1/share

Toggle Recording​

Start/stop meeting recording.

POST /v1/record

Leave Meeting​

End participation in the current meeting.

POST /v1/leave

Custom Actions​

Execute custom actions you've configured in MuteDeck.

POST /v1/custom/{action_name}

Example:

POST /v1/custom/raise-hand

Replace {action_name} with the name of your custom action as configured in MuteDeck settings.

WebSocket Support​

For real-time status updates, MuteDeck provides WebSocket connections:

const ws = new WebSocket('ws://localhost:3491');
// first, identify as a plugin before MuteDeck sends updates
ws.onopen = function() {
  const identify = {
    source: "plugin",
    action: "identify",
  };
	ws.send(JSON.stringify(identify));
};
// Listen for status updates
ws.onmessage = function(event) {
  const status = JSON.parse(event.data);
  console.log('Meeting status updated:', status);
};

Network Configuration​

Listen on All IPs​

By default, MuteDeck accepts connections from all hosts. To only allow connections from localhost, and not from other devices on your network, you can set the api_listen_on_all_ips setting to false:

Windows​

  1. Open Registry Editor
  2. Navigate to: HKEY_CURRENT_USER\Software\MuteDeck\MuteDeck
  3. Create String Value: api_listen_on_all_ips
  4. Set value to: false

Windows registry setting

macOS​

Open Terminal and run:

defaults write ~/Library/Preferences/com.mutedeck.MuteDeck.plist "api_listen_on_all_ips" 0
defaults read ~/Library/Preferences/com.mutedeck.MuteDeck.plist "api_listen_on_all_ips"

The last command should return 0 to confirm the setting.

To enable network access:

  • Windows: Set registry value to true
  • macOS: Use 1 instead of 0 in the command

Example Integrations​

Python Status Check​

import requests

def get_mutedeck_status():
    try:
        response = requests.get('http://localhost:3491/v1/status')
        return response.json()
    except requests.exceptions.RequestException:
        return {"error": "MuteDeck not running"}

status = get_mutedeck_status()
print(f"Muted: {status.get('mute') == 'active'}")

JavaScript Mute Toggle​

async function toggleMute() {
    try {
        const response = await fetch('http://localhost:3491/v1/mute', {
            method: 'POST'
        });
        const result = await response.json();
        console.log('Mute toggled:', result);
    } catch (error) {
        console.error('Error toggling mute:', error);
    }
}

Home Assistant Integration​

# configuration.yaml
rest_command:
  mutedeck_mute:
    url: "http://localhost:3491/v1/mute"
    method: POST

sensor:
  - platform: rest
    resource: http://localhost:3491/v1/status
    name: "MuteDeck Status"
    json_attributes:
      - mute
      - video
      - call
      - control

Node.js WebSocket Listener​

const WebSocket = require('ws');

const ws = new WebSocket('ws://localhost:3491/ws');

ws.on('message', function(data) {
    const status = JSON.parse(data);

    if (status.mute === 'active') {
        console.log('You are muted');
    } else if (status.mute === 'inactive') {
        console.log('You are unmuted');
    }
});

Error Handling​

Common HTTP Status Codes​

  • 200: Success
  • 400: Bad Request (invalid parameters)
  • 404: Endpoint not found
  • 500: Internal server error
  • 503: MuteDeck not ready/no meeting detected

Connection Errors​

  • Connection refused: MuteDeck not running
  • Timeout: MuteDeck may be busy or unresponsive
  • Network unreachable: Check firewall settings

Rate Limiting​

The API has built-in rate limiting to prevent abuse:

  • Maximum 100 requests per minute per client
  • WebSocket connections: Limited to 10 concurrent connections
  • Status polling: Recommended interval of 1 second or more

Webhook Notifications​

MuteDeck can send status updates to external URLs:

  1. Enable webhooks in MuteDeck settings
  2. Enter your webhook URL
  3. Receive POST requests with status updates

Webhook payload format:

{
  "control": "zoom",
  "mute": "active",
  "video": "inactive",
  "share": "inactive",
  "record": "disabled",
  "timestamp": "2025-01-26T10:30:00Z"
}

Use Cases​

Home Automation​

  • Smart lights: Change color when muted/unmuted
  • Door signs: Show "In Meeting" status
  • Smart speakers: Announce meeting status changes

Productivity Tools​

  • Time tracking: Start/stop timers based on meeting status
  • Status updates: Update Slack status automatically
  • Focus modes: Enable do-not-disturb when in meetings

Custom Hardware​

  • LED indicators: Show mute status on custom devices
  • Physical buttons: Create hardware mute toggles
  • Dashboard displays: Show meeting status on screens

Development Tools​

  • CI/CD integration: Pause builds during important meetings
  • Monitoring: Include meeting status in system dashboards
  • Automation: Trigger actions based on meeting state

Support and Examples​

Community Projects​

Check out community-created integrations and examples on our website and GitHub.

Getting Help​

  • API documentation: Visit http://localhost:3491 while MuteDeck is running
  • Contact support: mutedeck.com/contact-us
  • Share your project: We'd love to hear about what you build!

Please let us know when you build something with the API, as we'd love to know what awesome creations are out there!