Skip to content

# API Documentation 📚

Welcome to the MCP Server API documentation. This guide covers all available endpoints, authentication methods, and integration patterns.

## API Overview

The MCP Server provides several API categories:

1. Core API - Basic device control and state management
2. SSE API - Real-time event subscriptions
3. Scene API - Scene management and automation
4. Voice API - Natural language command processing

## Authentication

All API endpoints require authentication using JWT tokens:

    # Include the token in your requests
    curl -H "Authorization: Bearer YOUR_JWT_TOKEN" http://localhost:3000/api/state

To obtain a token:

    curl -X POST http://localhost:3000/auth/token \
      -H "Content-Type: application/json" \
      -d '{"username": "your_username", "password": "your_password"}'

## Core Endpoints

### Device State

    GET /api/state

Retrieve the current state of all devices:

    curl http://localhost:3000/api/state

Response:

    {
      "devices": [
        {
          "id": "light.living_room",
          "state": "on",
          "attributes": {
            "brightness": 255,
            "color_temp": 370
          }
        }
      ]
    }

### Command Execution

    POST /api/command

Execute a natural language command:

    curl -X POST http://localhost:3000/api/command \
      -H "Content-Type: application/json" \
      -d '{"command": "Turn on the kitchen lights"}'

Response:

    {
      "success": true,
      "action": "turn_on",
      "device": "light.kitchen",
      "message": "Kitchen lights turned on"
    }

## Real-Time Events

### Event Subscription

    GET /subscribe_events

Subscribe to device state changes:

    const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_TOKEN');

    eventSource.onmessage = (event) => {
        const data = JSON.parse(event.data);
        console.log('State changed:', data);
    };

### Filtered Subscriptions

Subscribe to specific device types:

    GET /subscribe_events?domain=light
    GET /subscribe_events?entity_id=light.living_room

## Scene Management

### Create Scene

    POST /api/scene

Create a new scene:

    curl -X POST http://localhost:3000/api/scene \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Movie Night",
        "actions": [
          {"device": "light.living_room", "action": "dim", "value": 20},
          {"device": "media_player.tv", "action": "on"}
        ]
      }'

### Activate Scene

    POST /api/scene/activate

Activate an existing scene:

    curl -X POST http://localhost:3000/api/scene/activate \
      -H "Content-Type: application/json" \
      -d '{"name": "Movie Night"}'

## Error Handling

The API uses standard HTTP status codes:

- `200` - Success
- `400` - Bad Request
- `401` - Unauthorized
- `404` - Not Found
- `500` - Server Error

Error responses include detailed messages:

    {
      "error": true,
      "message": "Device not found",
      "code": "DEVICE_NOT_FOUND",
      "details": {
        "device_id": "light.nonexistent"
      }
    }

## Rate Limiting

API requests are rate-limited to prevent abuse:

    X-RateLimit-Limit: 100
    X-RateLimit-Remaining: 99
    X-RateLimit-Reset: 1640995200

When exceeded, returns `429 Too Many Requests`:

    {
      "error": true,
      "message": "Rate limit exceeded",
      "reset": 1640995200
    }

## WebSocket API

For bi-directional communication:

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

    ws.onmessage = (event) => {
        const data = JSON.parse(event.data);
        console.log('Received:', data);
    };

    ws.send(JSON.stringify({
        type: 'command',
        payload: {
            command: 'Turn on lights'
        }
    }));

## API Versioning

The current API version is v1. Include the version in the URL:

    /api/v1/state
    /api/v1/command

## Further Reading

- SSE API Details - In-depth SSE documentation
- Core Functions - Detailed endpoint documentation
- Architecture Overview - System design details
- Troubleshooting - Common issues and solutions

# API Reference

The Advanced Home Assistant MCP provides several APIs for integration and automation:

- Core API - Primary interface for system control
- SSE API - Server-Sent Events for real-time updates
- Core Functions - Essential system functions

February 6, 2025
February 5, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings