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:

[
  {
    "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

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()

1.8 KiB Raw Blame History