Skip to content

# Core Functions API 🔧

The Core Functions API provides the fundamental operations for interacting with Home Assistant devices and services through MCP Server.

## Device Control

### Get Device State

Retrieve the current state of devices.

    GET /api/state
    GET /api/state/{entity_id}

Parameters: - `entity_id` (optional): Specific device ID to query

    # Get all states
    curl http://localhost:3000/api/state

    # Get specific device state
    curl http://localhost:3000/api/state/light.living_room

Response:

    {
      "entity_id": "light.living_room",
      "state": "on",
      "attributes": {
        "brightness": 255,
        "color_temp": 370,
        "friendly_name": "Living Room Light"
      },
      "last_changed": "2024-01-20T15:30:00Z"
    }

### Control Device

Execute device commands.

    POST /api/device/control

Request body:

    {
      "entity_id": "light.living_room",
      "action": "turn_on",
      "parameters": {
        "brightness": 200,
        "color_temp": 400
      }
    }

Available actions: - `turn_on` - `turn_off` - `toggle` - `set_value`

Example with curl:

    curl -X POST http://localhost:3000/api/device/control \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_JWT_TOKEN" \
      -d '{
        "entity_id": "light.living_room",
        "action": "turn_on",
        "parameters": {
          "brightness": 200
        }
      }'

## Natural Language Commands

### Execute Command

Process natural language commands.

    POST /api/command

Request body:

    {
      "command": "Turn on the living room lights and set them to 50% brightness"
    }

Example usage:

    curl -X POST http://localhost:3000/api/command \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_JWT_TOKEN" \
      -d '{
        "command": "Turn on the living room lights and set them to 50% brightness"
      }'

Response:

    {
      "success": true,
      "actions": [
        {
          "entity_id": "light.living_room",
          "action": "turn_on",
          "parameters": {
            "brightness": 127
          },
          "status": "completed"
        }
      ],
      "message": "Command executed successfully"
    }

## Scene Management

### Create Scene

Define a new scene with multiple actions.

    POST /api/scene

Request body:

    {
      "name": "Movie Night",
      "description": "Perfect lighting for movie watching",
      "actions": [
        {
          "entity_id": "light.living_room",
          "action": "turn_on",
          "parameters": {
            "brightness": 50,
            "color_temp": 500
          }
        },
        {
          "entity_id": "cover.living_room",
          "action": "close"
        }
      ]
    }

### Activate Scene

Trigger a predefined scene.

    POST /api/scene/{scene_name}/activate

Example:

    curl -X POST http://localhost:3000/api/scene/movie_night/activate \
      -H "Authorization: Bearer YOUR_JWT_TOKEN"

## Groups

### Create Device Group

Create a group of devices for collective control.

    POST /api/group

Request body:

    {
      "name": "Living Room",
      "entities": [
        "light.living_room_main",
        "light.living_room_accent",
        "switch.living_room_fan"
      ]
    }

### Control Group

Control multiple devices in a group.

    POST /api/group/{group_name}/control

Request body:

    {
      "action": "turn_off"
    }

## System Operations

### Health Check

Check server status and connectivity.

    GET /health

Response:

    {
      "status": "healthy",
      "version": "1.0.0",
      "uptime": 3600,
      "homeAssistant": {
        "connected": true,
        "version": "2024.1.0"
      }
    }

### Configuration

Get current server configuration.

    GET /api/config

Response:

    {
      "server": {
        "port": 3000,
        "host": "0.0.0.0",
        "version": "1.0.0"
      },
      "homeAssistant": {
        "url": "http://homeassistant:8123",
        "connected": true
      },
      "features": {
        "nlp": true,
        "scenes": true,
        "groups": true
      }
    }

## Error Handling

All endpoints follow standard HTTP status codes and return detailed error messages:

    {
      "error": true,
      "code": "INVALID_ENTITY",
      "message": "Device 'light.nonexistent' not found",
      "details": {
        "entity_id": "light.nonexistent",
        "available_entities": [
          "light.living_room",
          "light.kitchen"
        ]
      }
    }

Common error codes: - `INVALID_ENTITY`: Device not found - `INVALID_ACTION`: Unsupported action - `INVALID_PARAMETERS`: Invalid command parameters - `AUTHENTICATION_ERROR`: Invalid or missing token - `CONNECTION_ERROR`: Home Assistant connection issue

## TypeScript Interfaces

    interface DeviceState {
      entity_id: string;
      state: string;
      attributes: Record<string, any>;
      last_changed: string;
    }

    interface DeviceCommand {
      entity_id: string;
      action: 'turn_on' | 'turn_off' | 'toggle' | 'set_value';
      parameters?: Record<string, any>;
    }

    interface Scene {
      name: string;
      description?: string;
      actions: DeviceCommand[];
    }

    interface Group {
      name: string;
      entities: string[];
    }

## Related Resources

- API Overview
- SSE API
- Architecture
- Examples

February 5, 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