Choosing an API

Homecast offers five ways to interact with your devices programmatically. Each targets a different use case.

Comparison

	REST	GraphQL	MCP	Webhooks	Control URLs	MQTT
Auth	Token / OAuth	Token / OAuth	OAuth / Token	N/A (signing secret)	None (share hash)	Broker credentials
Complexity	Low	Medium	Low (AI handles it)	Medium	Very low	Medium
Real-time	No	No	No	Yes (push)	No	Yes (subscribe)
Batch ops	Yes	Yes	Yes	N/A	No	No
Best for	Scripts, cURL	Apps, dashboards	AI assistants	Event automations	Quick device control	Home Assistant, IoT
Reference	REST	GraphQL	MCP	Webhooks	Share Links	MQTT

REST

Simple JSON endpoints for reading state, controlling devices, and running scenes. No query language to learn.

# Read state
curl https://api.homecast.cloud/rest/state \
  -H "Authorization: Bearer hc_..."

# Turn on a light
curl -X POST https://api.homecast.cloud/rest/state \
  -H "Authorization: Bearer hc_..." \
  -H "Content-Type: application/json" \
  -d '[{"home": "My Home", "room": "Living Room", "accessory": "Floor Lamp", "on": true}]'

See Automation Scripts for more examples. Full reference: REST.

GraphQL

Fetch exactly the data you need in a single request. Supports queries, mutations, and the full Homecast schema including collections, webhooks, tokens, and OAuth management.

{
  accessories(homeId: "...") {
    id
    name
    services { type characteristics { type value } }
  }
}

Full reference: GraphQL.

MCP

The AI connects directly via the Model Context Protocol — no code needed on your part. The AI discovers available tools (get_state, set_state, run_scene) automatically.

{
  "mcpServers": {
    "homecast": {
      "type": "url",
      "url": "https://api.homecast.cloud/mcp"
    }
  }
}

See AI Assistant for setup. Full reference: MCP.

Webhooks

Homecast pushes HTTP notifications to your endpoint when device state changes — no polling required. Configure which events, homes, rooms, or accessories to subscribe to.

{
  "type": "state.changed",
  "data": {
    "accessoryName": "Motion Sensor",
    "characteristicType": "motion_detected",
    "value": true
  }
}

See Webhook Automation for setup. Full reference: Webhooks.

Control URLs

URL-based device state and control through share links. No authentication, no request body — just a GET request.

# Read current state (works with any role — view or control)
curl https://api.homecast.cloud/s/{hash}

# Turn on (requires control role)
curl https://api.homecast.cloud/s/{hash}/on

# Set brightness to 75%
curl https://api.homecast.cloud/s/{hash}/brightness/75

# Set color (hue 240, saturation 100)
curl https://api.homecast.cloud/s/{hash}/color/240/100

# Toggle power
curl https://api.homecast.cloud/s/{hash}/toggle

Full reference: Share Links.

MQTT

Homecast publishes device state to MQTT topics and accepts commands. Follows the Zigbee2MQTT convention. Works with any MQTT broker. Supports Home Assistant auto-discovery.

homecast/{home}/{room}/{accessory}              → device state (retained JSON)
homecast/{home}/{room}/{accessory}/set          ← control commands
homecast/{home}/{room}/{accessory}/availability → online/offline
homecast/{home}/{room}/{group}                  → service group state
homecast/{home}/{room}/{group}/set              ← control entire group
homecast/{home}/scene/{scene}/execute           ← trigger scene

Slugs use the format {name}-{first 4 hex of UUID} (e.g., kitchen-dfee).

Cloud plan includes the managed Homecast MQTT Broker at mqtt.homecast.cloud (port 8883 TLS). Authenticate with your API access token as the MQTT password. Browse topics live at mqtt.homecast.cloud.

All editions support custom MQTT brokers — connect to your own Mosquitto, EMQX, or HiveMQ instance.

Authentication quick reference

API	Auth method	How to get credentials
REST	API Token or OAuth	Create a token
GraphQL	API Token or OAuth	Create a token
MCP	OAuth 2.1 or API Token	Automatic via MCP client
Webhooks	N/A	Configured per webhook (signing secret)
Control URLs	None	Create a share link with control role
MQTT	API Token as password	Create a token, use as MQTT password

Home Assistant

Use Apple Home alongside Home Assistant? The Homecast integration makes your HomeKit devices available as native HA entities. Install via HACS, authorize with OAuth, and your devices appear in HA — ready for dashboards, automations, and voice assistants.

Still not sure?

• Start with REST — it's the simplest and works for most scripting needs
• Add webhooks when you need to react to events without polling
• Move to GraphQL when you need more flexible queries or management operations
• Use MCP if you're integrating with an AI assistant
• Use control URLs for the simplest possible integration — just hit a URL
• Use MQTT for real-time integration with Home Assistant or other IoT platforms
• Use Home Assistant to use your HomeKit devices alongside other HA integrations