# Homelable Backend Direct REST API Reference

Instead of negotiating a complex and slow Server-Sent Events (SSE) stream over port `8001` (which requires async JSON-RPC sessions and frequently times out), query the REST API on `homelable-backend` directly.

## Endpoint & Port
- **Host Port:** `9445`
- **Base URL:** `http://localhost:9445/api/v1`

## Authentication Header
The backend is authenticated using a special service key header:
```
X-MCP-Service-Key: <MCP_SERVICE_KEY>
```

### Loading Credentials Dynamically
To keep keys safe and secure (without leaking them to the LLM context window), read the key dynamically from the local `.env` configuration file:
- **Path:** `/srv/configs/docker_compose/homelabel/.env`
- **Variable Name:** `MCP_SERVICE_KEY`

## Common Endpoints

### 1. Health Check
- **Path:** `/api/v1/health`
- **Method:** `GET`
- **Response:** `{"status": "ok"}`

### 2. Retrieve Nodes (Canvas Devices)
- **Path:** `/api/v1/nodes`
- **Method:** `GET`
- **Response:** Array of node objects:
```json
[
  {
    "id": "3fc16e75-9418-41b1-b4a2-d3859c9ce431",
    "type": "computer",
    "label": "Game Pc",
    "ip": "10.0.0.109",
    "status": "online",
    "services": [
      {
        "port": 11434,
        "protocol": "tcp",
        "service_name": "Ollama"
      }
    ]
  }
]
```

## Python Integration Example

```python
import os
import requests

env_path = "/srv/configs/docker_compose/homelabel/.env"
service_key = ""

if os.path.exists(env_path):
    with open(env_path, "r") as f:
        for line in f:
            if line.startswith("MCP_SERVICE_KEY="):
                service_key = line.split("=", 1)[1].strip()

headers = {"X-MCP-Service-Key": service_key}
resp = requests.get("http://localhost:9445/api/v1/nodes", headers=headers)
nodes = resp.json()
```