# API Overview

Introduction to DWN's WebSocket API

## Introduction

DWN provides a WebSocket API for full programmatic control of the window manager. This enables:

- Test Automation - Automated UI testing and scripting
- Custom Hotkeys - Build custom keyboard shortcuts
- Remote Control - Control DWN from other machines or devices
- Integration - Connect DWN to other applications
- Accessibility - Build alternative input methods

## Enabling the API

The API is disabled by default. Enable it in `~/.config/dwn/config`:

    [api]
    enabled = true
    port = 8777

Restart DWN for changes to take effect.

Security Note: The API listens on localhost only by default. Be cautious when exposing to network.

## Connecting

Connect via WebSocket to `ws://localhost:8777/ws` (or your configured port). The `/ws` path is required.

### Testing with wscat

    # Install wscat
    npm install -g wscat

    # Connect to DWN
    wscat -c ws://localhost:8777/ws

    # Send a command
    > {"command": "get_clients"}
    < {"status": "ok", "clients": [...]}

### Testing with websocat

    # Install websocat
    cargo install websocat

    # Connect and send command
    echo '{"command": "get_clients"}' | websocat ws://localhost:8777/ws

## Protocol

### Request Format

All requests are JSON objects with a `command` field:

    {
        "command": "command_name",
        "param1": "value1",
        "param2": "value2"
    }

### Response Format

Responses include a `status` field:

    // Success
    {
        "status": "ok",
        "data": {...}
    }

    // Error
    {
        "status": "error",
        "message": "Error description"
    }

### Command Categories

Category | Commands
--- | ---
Clients | get_clients, find_clients, get_focused_client, focus_client, focus_next, focus_prev, focus_master, close_client, kill_client, move_client, resize_client, minimize_client, restore_client, maximize_client, fullscreen_client, float_client, raise_client, lower_client, snap_client
Workspaces | get_workspaces, switch_workspace, switch_workspace_next, switch_workspace_prev, move_client_to_workspace
Layout | set_layout, cycle_layout, set_master_ratio, adjust_master_ratio, set_master_count, adjust_master_count
Keyboard | key_press, key_release, key_tap, key_type, get_keybindings
Mouse | mouse_move, mouse_move_relative, mouse_click, mouse_press, mouse_release, mouse_scroll, get_mouse_position
Screenshot | screenshot
OCR | ocr
System | get_status, get_screen_info, run_command, show_desktop, get_config, reload_config
Notifications | notify, close_notification, get_notifications
System Tray | get_battery_state, get_audio_state, set_audio_volume, toggle_audio_mute, get_wifi_state
Panels | get_panel_state, show_panel, hide_panel, toggle_panel
AI | ai_is_available, ai_command, exa_is_available, exa_search
News | get_news, news_next, news_prev, news_open
Demo/Tutorial | start_demo, stop_demo, get_demo_state, start_tutorial, stop_tutorial, get_tutorial_state
Events | subscribe, unsubscribe, list_events
Fade Effects | get_fade_settings, set_fade_speed, set_fade_intensity

## Quick Start

### List Clients

    // Request
    {"command": "get_clients"}

    // Response
    {
        "status": "ok",
        "clients": [
            {
                "window": 12345678,
                "title": "Firefox",
                "class": "firefox",
                "workspace": 0,
                "x": 0, "y": 32,
                "width": 960, "height": 540,
                "focused": true,
                "floating": false,
                "fullscreen": false,
                "maximized": false,
                "minimized": false
            }
        ]
    }

### Focus a Client

    {"command": "focus_client", "window": 12345678}

### Switch Workspace

    {"command": "switch_workspace", "workspace": 2}

### Type Text

    {"command": "key_type", "text": "Hello, World!"}

### Take Screenshot

    // Request
    {"command": "screenshot", "mode": "fullscreen"}

    // Response
    {
        "status": "ok",
        "format": "png",
        "encoding": "base64",
        "width": 1920,
        "height": 1080,
        "data": "iVBORw0KGgo..."
    }

## Client Libraries

### Python Client

A Python client is included in the `examples/` directory:

    from dwn_api_client import DWNClient

    # Connect
    client = DWNClient()
    client.connect()

    # List clients
    clients = client.get_clients()

    # Focus a client
    client.focus_client(clients[0]['window'])

    # Take screenshot
    result = client.screenshot('fullscreen')
    with open('screenshot.png', 'wb') as f:
        f.write(base64.b64decode(result['data']))

    # Disconnect
    client.disconnect()

### JavaScript (Browser)

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

    ws.onopen = () => {
        ws.send(JSON.stringify({command: 'get_clients'}));
    };

    ws.onmessage = (event) => {
        const response = JSON.parse(event.data);
        console.log(response);
    };

### Web Remote

A web-based remote control interface is included at `examples/web_remote.html`. Open it in a browser to control DWN graphically.

## Next Steps

- API Reference - Complete command documentation
- API Examples - Code examples for common tasks