Domotz API Patterns

Domotz MCP Tools & API Patterns

Overview

The Domotz MCP server provides AI tool integration with the Domotz network monitoring and management platform. It exposes tools covering agents, devices, alerts, network scanning, SNMP, port monitoring, speed tests, and Domotz Eyes sensors. The API authenticates with an API key passed via the X-Api-Key header.

Connection & Authentication

API Key Authentication

Domotz authenticates using an API key passed as an HTTP header:

Header	Description
X-Domotz-API-Key	Your Domotz API key
X-Domotz-Region	API region (us-east-1 or eu-central-1)

Generate credentials at: Domotz Portal > User Menu > API Keys

Environment Variables:

export DOMOTZ_API_KEY="your-api-key"
export DOMOTZ_REGION="us-east-1"

IMPORTANT: Never hardcode credentials. Always use environment variables.

Regional Endpoints

Domotz operates region-specific API endpoints:

Region	API Host
us-east-1 (default)	api-us-east-1-cell-1.domotz.com
eu-central-1	api-eu-central-1-cell-1.domotz.com

Ensure your region matches your Domotz account's region. Using the wrong region returns authentication errors.

Available MCP Tools

Agents

Tool	Description
domotz_list_agents	List all Domotz agents/collectors
domotz_get_agent	Get details for a specific agent
domotz_get_agent_status	Get agent connectivity status

Devices

Tool	Description
domotz_list_devices	List devices monitored by an agent
domotz_get_device	Get device details by ID
domotz_search_devices	Search devices by name, IP, or MAC
domotz_get_device_status	Get device online/offline status

Alerts

Tool	Description
domotz_list_alerts	List active alerts
domotz_get_alert	Get alert details
domotz_list_alert_profiles	List configured alert profiles

Network

Tool	Description
domotz_scan_network	Trigger a network discovery scan
domotz_list_snmp_data	Get SNMP polled data for a device
domotz_list_ports	List open ports on a device
domotz_run_speed_test	Run a speed test from an agent

Domotz Eyes

Tool	Description
domotz_list_eyes	List Domotz Eyes sensors for an agent
domotz_get_eye	Get sensor details and status
domotz_list_eye_results	Get historical results for a sensor

Pagination

The Domotz API uses offset-based pagination:

• Pass page (1-indexed) and page_size to control result pages
• The response includes count for total number of results
• Continue fetching pages until all results are retrieved

Example workflow:

1. Call domotz_list_devices with agent_id and page=1, page_size=50
2. If count exceeds 50, call again with page=2
3. Repeat until all pages are fetched

Rate Limiting

Domotz enforces API rate limits per API key.

• HTTP 429 responses indicate rate limit exceeded
• Wait before retrying -- use exponential backoff
• Batch operations where possible
• Use filters to reduce result set sizes

Error Handling

Common Error Codes

Code	Meaning	Resolution
401	Unauthorized	Check API key; verify region matches account
403	Forbidden	Insufficient permissions for this resource
404	Not Found	Resource doesn't exist or wrong ID
429	Rate Limited	Wait and retry after delay
500	Server Error	Retry; contact support if persistent

Error Response Format

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Best Practices

• Always specify the correct region to avoid authentication errors
• Paginate through full result sets for complete device inventories
• Use agent ID filters to scope queries to specific sites
• Cache agent and device info to reduce API calls
• Handle rate limits gracefully with backoff
• Monitor last_seen timestamps to detect offline agents/devices

Related Skills

• agents - Agent and site management
• devices - Device inventory and discovery
• alerts - Alert profiles and triggers
• network - Network scanning and SNMP
• eyes - Domotz Eyes sensors