Domotz API Patterns · diff

git:20260728.b7e78fc to git:20260806.ad583a2

135 added, 74 removed. Audit A to A.

---

name: "Domotz API Patterns"

description: >

- Domotz API and MCP fundamentals: API-key header authentication, region-specific

- endpoints (us-east-1 / eu-central-1), the full MCP tool catalog by domain,

- offset-based pagination, rate limiting, and HTTP error codes.

+ Domotz API and MCP fundamentals: X-Api-Key header authentication, the

+ region-selected base URL (us-east-1 / eu-central-1), the full 21-tool MCP

+ catalog by domain, the agent-scoped call shape, why there are no pagination

+ arguments, rate limiting, and HTTP error codes.

when_to_use: >-

When authenticating to or calling the Domotz API directly or through the MCP

tools, or when discovering which Domotz tool to use. Use when: domotz api, domotz authentication, domotz

pagination, domotz rate limit, domotz mcp, domotz tools, domotz request, domotz error, domotz

connection, or domotz region.

---

# 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.

+ 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.

## Connection & Authentication

### API Key Authentication

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

+ Domotz authenticates with a single HTTP header:

- | Header | Description |

- |--------|-------------|

- | `X-Domotz-API-Key` | Your Domotz API key |

- | `X-Domotz-Region` | API region (`us-east-1` or `eu-central-1`) |

+ | 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/v1

+ ```

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

- **Environment Variables:**

+ **Environment Variables (self-hosted / stdio mode):**

```bash

export DOMOTZ_API_KEY="your-api-key"

- export DOMOTZ_REGION="us-east-1"

+ export DOMOTZ_REGION="us-east-1" # default when unset

```

- > **IMPORTANT:** Never hardcode credentials. Always use environment variables.

+ Through the WYRE Conduit gateway you set neither — Conduit holds the key

+ and injects both per request. See `GOVERNANCE.md`.

- ### Regional Endpoints

+ > **IMPORTANT:** Never hardcode credentials.

- Domotz operates region-specific API endpoints:

+ ### Regional Endpoints

- | Region | API Host |

+ | Region | Base URL |

|--------|----------|

- | `us-east-1` (default) | `api-us-east-1-cell-1.domotz.com` |

- | `eu-central-1` | `api-eu-central-1-cell-1.domotz.com` |

+ | `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` |

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

+ A credential issued for one region cannot see the other's data. A region

+ mismatch surfaces as an authentication error, not an empty result.

+ ## The call shape: everything is agent-scoped

+ 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.

## Available MCP Tools

- ### Agents

+ ### Navigation

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

+ | `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.

+ ### Agents

+ | Tool | Arguments |

+ |------|-----------|

+ | `domotz_agents_list` | *(none)* — every agent on the account |

+ | `domotz_agents_get` | `agent_id` |

### 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 |

+ | 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` |

- ### Alerts

+ There is no device search tool. Matching by name, IP, or MAC is done

+ client-side over the `domotz_devices_list` result.

- | Tool | Description |

- |------|-------------|

- | `domotz_list_alerts` | List active alerts |

- | `domotz_get_alert` | Get alert details |

- | `domotz_list_alert_profiles` | List configured alert profiles |

+ ### Metrics (SNMP)

+ | 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.

### 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 |

+ | Tool | Arguments |

+ |------|-----------|

+ | `domotz_network_topology` | `agent_id` |

+ | `domotz_network_interfaces` | `agent_id` |

+ | `domotz_network_ip_conflicts` | `agent_id` |

- ### Domotz Eyes

+ `domotz_network_interfaces` returns the *collector's* own network

+ interfaces. It is not a per-device port or interface list.

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

+ ### Alerts

- ## Pagination

+ | Tool | Arguments |

+ |------|-----------|

+ | `domotz_alerts_profiles_list` | *(none)* — every alert profile on the account |

+ | `domotz_alerts_device_list` | `agent_id`, `device_id` |

- The Domotz API uses offset-based pagination:

+ Both describe alert *configuration*. Neither returns a fired alert — see

+ the `alerts` skill.

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

+ ### Power

- **Example workflow:**

+ | 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` |

- 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

+ `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.

+ ## Pagination

+ **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.

## 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

+ - HTTP 429 indicates the limit was exceeded

+ - Back off exponentially before retrying

+ - The main way to reduce call volume is to avoid fanning out over every

+ agent when one `agent_id` would do — there are no batch arguments

## 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 |

+ | 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 |

- ### Error Response Format

+ The server surfaces failures as `Domotz API error <status>: <body>`; the

+ upstream body is passed through unmodified.

- ```json

- {

- "error": "Unauthorized",

- "message": "Invalid API key"

- }

- ```

+ A denial through Conduit looks different from a Domotz error — most Domotz

+ tools are unclassified and therefore require `admin`. Check

+ `conduit__my_access` before treating a refusal as a credential problem.

## Best Practices

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

- - Monitor `last_seen` timestamps to detect offline agents/devices

+ - Scope by `agent_id`; fan out over agents only when the question really

+ is fleet-wide

+ - Cache agent and device lists — they change slowly and every other call

+ needs their IDs

+ - Check the agent's own status before trusting device status; a dead

+ collector serves last-known data that reads as current

+ - Monitor `last_seen` timestamps to detect offline agents and devices

## Related Skills

- [agents](../agents/SKILL.md) - Agent and site management

- [devices](../devices/SKILL.md) - Device inventory and discovery

- - [alerts](../alerts/SKILL.md) - Alert profiles and triggers

- - [network](../network/SKILL.md) - Network scanning and SNMP

- - [eyes](../eyes/SKILL.md) - Domotz Eyes sensors

+ - [alerts](../alerts/SKILL.md) - Alert profiles and device bindings

+ - [network](../network/SKILL.md) - Topology, interfaces, and SNMP metrics

+ - [power](../power/SKILL.md) - PDU outlet control