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​

From v4.13, create API tokens in Settings → Plugins & API → Create API token. Name the token and copy it before closing the dialog; MuteDeck cannot show it again. See managing API tokens.

Include the token in each request:

curl http://localhost:3491/v1/status \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Requests without a token follow Settings → Plugins & API → Plugins without authentication:

  • Allow (default): existing unauthenticated requests keep working.
  • Allow from this computer only: requests from another computer need a token.
  • Block: all API requests to meeting status and control endpoints need a token, including local requests.

A supplied token must be valid even when unauthenticated access is allowed. Deleting a token in Settings revokes it.

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 on port 3492 (unencrypted) or 3493 (TLS).

The examples on this page use the older, unauthenticated plugin connection. They work only when Plugins without authentication permits the connection. An HTTP Bearer header is for REST requests; authenticated WebSocket plugins use the plugin approval handshake.

const ws = new WebSocket('ws://localhost:3492');
// 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​

Set the MUTEDECK_API_TOKEN environment variable to a token you created in Settings.

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['MUTEDECK_API_TOKEN']}"}

def get_mutedeck_status():
    try:
        response = requests.get(
            'http://localhost:3491/v1/status', headers=headers, timeout=5
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as error:
        return {"error": str(error)}

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

JavaScript Mute Toggle​

Replace YOUR_API_TOKEN with your token. Keep this example in a private local tool; do not publish your token in a web page.

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

Home Assistant Integration​

Store mutedeck_authorization: "Bearer YOUR_API_TOKEN" in Home Assistant's secrets.yaml. If Home Assistant runs on another computer, replace localhost below with the address of the computer running MuteDeck.

# configuration.yaml
rest_command:
  mutedeck_mute:
    url: "http://localhost:3491/v1/mute"
    method: POST
    headers:
      Authorization: !secret mutedeck_authorization

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

There's a dedicated guide for integrating MuteDeck with Home Assistant that uses webhooks for real-time updates. The above example uses a polling approach, which is less efficient.

Node.js WebSocket Listener​

const WebSocket = require('ws');

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

ws.on('open', function() {
    ws.send(JSON.stringify({ source: 'plugin', action: 'identify' }));
});

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)
  • 401: Invalid or revoked token, or a remote request without a token when only local unauthenticated access is allowed
  • 426: Authentication is required because Plugins without authentication is set to Block
  • 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. Open Settings → Integrations and turn on Enable Webhook
  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!