diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..afe9c8d
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,364 @@
+# Home Assistant MCP API Documentation
+
+## Overview
+
+The Home Assistant Model Context Protocol (MCP) Server provides a comprehensive API for managing and controlling your Home Assistant instance. This document outlines all available endpoints, their parameters, and includes practical examples.
+
+## Authentication
+
+All API requests require authentication using a Bearer token.
+
+```http
+Authorization: Bearer your_home_assistant_token
+```
+
+## Rate Limiting
+
+The API implements rate limiting with the following defaults:
+- 100 requests per 15-minute window per IP
+- Model-specific limits:
+  - Claude: 100 requests/minute, 1000/hour
+  - GPT-4: 50 requests/minute, 500/hour
+  - Custom: 200 requests/minute, 2000/hour
+
+## Endpoints
+
+### 1. Natural Language Processing
+
+#### POST /interpret
+
+Interprets natural language commands for Home Assistant control.
+
+**Request Body:**
+```json
+{
+  "input": "Turn on the living room lights",
+  "context": {
+    "user_id": "user123",
+    "session_id": "sess456",
+    "timestamp": "2024-03-20T10:30:00Z",
+    "location": "home",
+    "previous_actions": [],
+    "environment_state": {}
+  },
+  "model": "claude"  // Optional: defaults to "claude"
+}
+```
+
+**Response:**
+```json
+{
+  "natural_language": "I'll turn on the living room lights",
+  "structured_data": {
+    "success": true,
+    "action_taken": "turn_on",
+    "entities_affected": ["light.living_room"],
+    "state_changes": {
+      "state": "on"
+    }
+  },
+  "next_suggestions": [
+    "Would you like to adjust the brightness?",
+    "Should I turn on other lights?",
+    "Would you like to save this as a scene?"
+  ],
+  "confidence": 0.95,
+  "context": {
+    "user_id": "user123",
+    "session_id": "sess456",
+    "timestamp": "2024-03-20T10:30:00Z"
+  }
+}
+```
+
+### 2. Device Control
+
+#### POST /control
+
+Controls Home Assistant devices and services.
+
+**Request Body:**
+```json
+{
+  "command": "turn_on",
+  "entity_id": "light.living_room",
+  "brightness": 255,
+  "color_temp": 4000,
+  "rgb_color": [255, 0, 0]
+}
+```
+
+**Example Commands by Device Type:**
+
+**1. Lights:**
+```json
+{
+  "command": "turn_on",
+  "entity_id": "light.bedroom",
+  "brightness": 128,
+  "color_temp": 3500
+}
+```
+
+**2. Climate:**
+```json
+{
+  "command": "set_temperature",
+  "entity_id": "climate.living_room",
+  "temperature": 72,
+  "hvac_mode": "heat"
+}
+```
+
+**3. Covers:**
+```json
+{
+  "command": "set_position",
+  "entity_id": "cover.garage",
+  "position": 50
+}
+```
+
+### 3. History
+
+#### GET /history
+
+Retrieves state history for entities.
+
+**Query Parameters:**
+- `entity_id` (required): Entity ID to get history for
+- `start_time` (optional): Start time in ISO format
+- `end_time` (optional): End time in ISO format
+- `minimal_response` (optional): Boolean to reduce response size
+- `significant_changes_only` (optional): Boolean to filter minor changes
+
+**Example Request:**
+```http
+GET /history?entity_id=light.living_room&start_time=2024-03-19T00:00:00Z&minimal_response=true
+```
+
+### 4. Scenes
+
+#### GET /scenes
+
+Lists all available scenes.
+
+**Response:**
+```json
+{
+  "success": true,
+  "scenes": [
+    {
+      "entity_id": "scene.movie_time",
+      "name": "Movie Time",
+      "description": "Dim lights and lower blinds"
+    }
+  ]
+}
+```
+
+#### POST /scenes/activate
+
+Activates a scene.
+
+**Request Body:**
+```json
+{
+  "scene_id": "scene.movie_time"
+}
+```
+
+### 5. Automations
+
+#### GET /automations
+
+Lists all automations.
+
+**Response:**
+```json
+{
+  "success": true,
+  "automations": [
+    {
+      "entity_id": "automation.morning_routine",
+      "name": "Morning Routine",
+      "state": "on",
+      "last_triggered": "2024-03-20T06:00:00Z"
+    }
+  ]
+}
+```
+
+#### POST /automations
+
+Creates or modifies automations.
+
+**Request Body (Create):**
+```json
+{
+  "action": "create",
+  "config": {
+    "alias": "Morning Routine",
+    "description": "Turn on lights at sunrise",
+    "trigger": {
+      "platform": "sun",
+      "event": "sunrise"
+    },
+    "action": {
+      "service": "light.turn_on",
+      "target": {
+        "entity_id": "light.living_room"
+      }
+    }
+  }
+}
+```
+
+### 6. Add-ons
+
+#### GET /addons
+
+Lists available add-ons.
+
+**Response:**
+```json
+{
+  "success": true,
+  "addons": [
+    {
+      "name": "File Editor",
+      "slug": "core_configurator",
+      "description": "Simple browser-based file editor",
+      "version": "5.6.0",
+      "installed": true,
+      "available": true,
+      "state": "started"
+    }
+  ]
+}
+```
+
+#### POST /addons
+
+Manages add-ons.
+
+**Request Body (Install):**
+```json
+{
+  "action": "install",
+  "slug": "core_configurator",
+  "version": "5.6.0"
+}
+```
+
+### 7. Package Management (HACS)
+
+#### GET /packages
+
+Lists available HACS packages.
+
+**Query Parameters:**
+- `category`: One of ["integration", "plugin", "theme", "python_script", "appdaemon", "netdaemon"]
+
+**Response:**
+```json
+{
+  "success": true,
+  "packages": [
+    {
+      "name": "Custom Component",
+      "repository": "owner/repo",
+      "category": "integration",
+      "installed_version": "1.0.0",
+      "available_version": "1.1.0"
+    }
+  ]
+}
+```
+
+#### POST /packages
+
+Manages HACS packages.
+
+**Request Body (Install):**
+```json
+{
+  "action": "install",
+  "category": "integration",
+  "repository": "owner/repo",
+  "version": "1.1.0"
+}
+```
+
+## Error Handling
+
+All endpoints return errors in a consistent format:
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human readable error message",
+    "suggestion": "Suggestion to fix the error",
+    "recovery_options": [
+      "Option 1",
+      "Option 2"
+    ]
+  }
+}
+```
+
+Common HTTP status codes:
+- 200: Success
+- 400: Bad Request
+- 401: Unauthorized
+- 403: Forbidden
+- 404: Not Found
+- 429: Too Many Requests
+- 500: Internal Server Error
+
+## WebSocket Events
+
+The server supports WebSocket connections for real-time updates.
+
+### Connection
+
+```javascript
+const ws = new WebSocket('ws://your-server/api/websocket');
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('Received:', data);
+};
+```
+
+### Event Subscription
+
+```javascript
+// Subscribe to all events
+ws.send(JSON.stringify({
+  type: 'subscribe_events'
+}));
+
+// Subscribe to specific event type
+ws.send(JSON.stringify({
+  type: 'subscribe_events',
+  event_type: 'state_changed'
+}));
+```
+
+## Security Best Practices
+
+1. Always use HTTPS in production
+2. Store tokens securely
+3. Implement proper token rotation
+4. Monitor and log API usage
+5. Regular security audits
+
+## Rate Limiting Headers
+
+The API includes rate limit information in response headers:
+```http
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1621436800
+``` 
\ No newline at end of file