Domotz API Patterns — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited Domotz API Patterns (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
The Domotz MCP server wraps the Domotz Public API v1 for network monitoring and management. It registers 21 tools covering agents (collectors), devices, SNMP metrics, network topology, alert profiles, and PDU power control. Twenty of them are GET requests; one — domotz_power_outlet_control — switches mains power.
Domotz authenticates with a single HTTP header:
| Header | Value |
|---|---|
X-Api-Key | Your Domotz API key |
There is no region header. Region selects the base URL host, not a header value:
https://api-{region}-cell-1.domotz.com/public-api/v1Generate credentials at: Domotz Portal > User Menu > API Keys
Environment Variables (self-hosted / stdio mode):
export DOMOTZ_API_KEY="your-api-key"
export DOMOTZ_REGION="us-east-1" # default when unsetThrough the WYRE Conduit gateway you set neither — Conduit holds the key and injects both per request. See GOVERNANCE.md.
IMPORTANT: Never hardcode credentials.
| Region | Base URL |
|---|---|
us-east-1 (default) | https://api-us-east-1-cell-1.domotz.com/public-api/v1 |
eu-central-1 | https://api-eu-central-1-cell-1.domotz.com/public-api/v1 |
A credential issued for one region cannot see the other's data. A region mismatch surfaces as an authentication error, not an empty result.
There is no account-wide query except domotz_agents_list. Every device, metric, network, and power tool requires an agent_id, and most also require a device_id. A fleet-wide answer means iterating agents explicitly — list agents, then loop. Omitting agent_id does not widen the query; it fails.
All IDs are numbers, not strings.
| Tool | Description |
|---|---|
domotz_navigate | Move to a domain (agents, devices, metrics, network, alerts, power) |
domotz_status | Check the server's Domotz connection and list available domains |
domotz_back | Return to the domain menu |
domotz_status reports the server's credential and connectivity state. It says nothing about whether a given collector is online — that is the status field on domotz_agents_get.
Through Conduit, domotz_navigate and domotz_back are refused for every caller at every tier and never appear in the tool list. Use conduit__my_access to discover what you can call. Direct/self-hosted callers see all three.
| Tool | Arguments |
|---|---|
domotz_agents_list | (none) — every agent on the account |
domotz_agents_get | agent_id |
| Tool | Arguments |
|---|---|
domotz_devices_list | agent_id |
domotz_devices_get | agent_id, device_id |
domotz_devices_uptime | agent_id, device_id |
domotz_devices_history | agent_id, device_id |
domotz_devices_inventory | agent_id, device_id |
There is no device search tool. Matching by name, IP, or MAC is done client-side over the domotz_devices_list result.
| Tool | Arguments |
|---|---|
domotz_metrics_variables_list | agent_id, device_id |
domotz_metrics_variable_history | agent_id, device_id, variable_id |
domotz_metrics_snmp_sensors_list | agent_id, device_id |
domotz_metrics_sensor_history | agent_id, device_id, sensor_id |
Variables are the metrics Domotz polls by default; sensors are custom SNMP sensors configured on the device. They are separate lists with separate history endpoints.
| Tool | Arguments |
|---|---|
domotz_network_topology | agent_id |
domotz_network_interfaces | agent_id |
domotz_network_ip_conflicts | agent_id |
domotz_network_interfaces returns the collector's own network interfaces. It is not a per-device port or interface list.
| Tool | Arguments |
|---|---|
domotz_alerts_profiles_list | (none) — every alert profile on the account |
domotz_alerts_device_list | agent_id, device_id |
Both describe alert configuration. Neither returns a fired alert — see the alerts skill.
| Tool | Arguments |
|---|---|
domotz_power_outlets_list | agent_id, device_id |
domotz_power_outlet_control | agent_id, device_id, outlet_id, action (on/off/cycle), confirm |
domotz_power_outlet_control is the only tool here that changes anything, and what it changes is mains power. Read the power skill before calling it.
No Domotz MCP tool accepts a page, page_size, offset, or limit argument. Each list tool returns its full result set in one response.
The practical consequence is the opposite of a pagination loop: a large site returns its entire device census in a single payload, so scope by agent_id and expect big responses rather than many small ones. If you need a subset, filter the returned array — do not look for a filter argument that does not exist.
Domotz enforces API rate limits per API key.
agent when one agent_id would do — there are no batch arguments
| 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 the ID belongs to a different agent |
| 429 | Rate Limited | Wait and retry after delay |
| 500 | Server Error | Retry; contact support if persistent |
The server surfaces failures as Domotz API error <status>: <body>; the upstream body is passed through unmodified.
Check conduit__my_access before treating a refusal as a credential problem.
agent_id; fan out over agents only when the question reallyis fleet-wide
needs their IDs
collector serves last-known data that reads as current
last_seen timestamps to detect offline agents and devices~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.