# Unitrends UniView API Patterns

> Unitrends UniView MCP fundamentals: the two Conduit credential headers and the OAuth2 client_credentials exchange behind them, the flat 12-tool read-only surface, the {data, paging} response shape, page_number/page_size paging and truncation, parameter validation (enums, UUIDs, ISO 8601, include objects), error and 429 handling, and which tools return personal data.

- Skill: `wyre-ai/unitrends-uniview-api-patterns` (Agent Skill)
- Install (CLI): `npx get-skill add wyre-ai/unitrends-uniview-api-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wyre-ai/unitrends-uniview-api-patterns/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: WYRE-AI (https://skillmd.com/u/wyre-ai)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/wyre-ai/unitrends-uniview-api-patterns

---


# Unitrends UniView API Patterns

## Overview

UniView is Kaseya's multi-tenant Unitrends portal at `backup.net`. Its public
API is read-only, and one credential reads every customer in the MSP's UniView
tenant. The MCP server exposes the 12 published operations as 12 tools, all
`GET`, all listed flat in `tools/list`.

## Anti-triggers

- **A single on-prem Unitrends appliance** (appliance base URL, username and
  password): that is the separate `unitrends` plugin, not UniView.
- **Kaseya's other backup products** (Datto BCDR, Datto SaaS Protection): this
  plugin speaks only the UniView API.

## Connection & Authentication

Conduit stores the credential, entered in the Conduit web UI
(`/connect/unitrends-uniview`), and sends it on every call as two headers.
Nothing is set on the client, and Conduit drops any `X-Unitrends-UniView-*`
header a client sends:

| Header | Conduit field |
|--------|---------------|
| `X-Unitrends-UniView-Client-ID` | Client ID |
| `X-Unitrends-UniView-Client-Secret` | Client Secret |

Create the credential in the UniView portal under the settings icon > API
Access > + New. The secret is shown once; the credential can be revoked on the
same page.

The MCP server exchanges the pair for a bearer token (OAuth2
`client_credentials` against `login.backup.net`) and caches it until shortly
before it expires. On a 401 it drops the token and retries once with a fresh
one, so a 401 that reaches you means the credential itself was rejected or
revoked.

## Tool Surface

| Tool | Required args | Notes |
|------|---------------|-------|
| `unitrends_uniview_customers_list` | none | Start here: customer `id` (UUID) filters every other tool |
| `unitrends_uniview_appliances_list` | none | `is_online`, `total_mb_free_to`, `version`, `helix_status` |
| `unitrends_uniview_backups_list` | none | `status`, `replication_status`, `start_time_from`/`_to`, `complete_time_from`/`_to` |
| `unitrends_uniview_backupiq_alerts_list` | `type` | `type` is one of `alert`, `job`, `conditional`, `helix` |
| `unitrends_uniview_assets_list` | none | `include: {"backups": "last"}` adds each asset's last backup |
| `unitrends_uniview_epb_assets_list` | none | Endpoint Backup devices |
| `unitrends_uniview_spanning_domains_list` | none | Users left out unless `include: {"users": "true"}` |
| `unitrends_uniview_spanning_domain_users_list` | `domain_id` | Personal data |
| `unitrends_uniview_spanning_domains_list_v1` | none | Older shape; prefer the v2 tool |
| `unitrends_uniview_spanning_domain_users_list_v1` | `domain_id` | Older shape; personal data |
| `unitrends_uniview_entra_domains_list` | none | Entra tenants and mapped customer |
| `unitrends_uniview_agent_latest_get` | none | Not paged |

**Conduit gating:** all 12 are plain reads in Conduit. None is admin-gated and
none writes. Confirm the live grant in the Conduit access editor.

## Response Shape

Every tool returns:

```json
{
  "data": [ ... ],
  "paging": { "page_number": 1, "page_size": 50, "total_records": 312, "total_pages": 7 }
}
```

`data` is UniView's JSON unchanged (a bare array for list tools). `paging` comes
from UniView's `Paging-*` response headers and is absent when UniView sends
none.

## Pagination

- List tools take `page_number` (1-based, default 1) and `page_size` (default
  50, capped at 1000).
- The server never pages for you. Read `paging.total_pages` and request each
  page. Never call a count or a "no failures" result complete from page 1 alone.
- When a page exceeds the server's output cap, items are dropped from the end
  of `data` and the response adds `truncated: true`, `returned_items`,
  `total_items_in_page` and a `truncation_hint`. Repeat with a smaller
  `page_size`.
- Narrow with filters (`customer_id`, `status`, time windows) before raising
  `page_size`.

## Parameters

- Enums are checked before the request: `status` is `Successful`, `Warning`,
  `Failed`, `InProgress` or `Unknown`; `replication_status` is `Successful`,
  `Failed` or `Unknown`; `severity` is `alarm`, `critical` or `warning`. Case
  matters.
- `customer_id`, `asset_key` and `key` must be UUIDs. `asset_tag` is the
  appliance ID string, not a UUID.
- Time filters are ISO 8601, e.g. `2026-11-01T00:00:00Z`.
- `include` is an object, not a string: `{"backups": "last", "links": "all"}`.
- Storage filters and sizes are in MB.
- Arguments a tool does not declare are dropped.

## Error Handling

Vendor errors come back as tool errors with the HTTP status, a hint, UniView's
`title`/`detail`, and a `request_id` when UniView sends one.

| Status | Meaning | Action |
|--------|---------|--------|
| 400 | A filter value UniView rejected | Check enum case, UUID and date formats |
| 401 | Credential rejected after a token refresh | Credential revoked or wrong; reconnect in Conduit |
| 403 | Credential not allowed to read this resource | Check the credential in UniView API Access |
| 404 | Unknown ID (for example a `domain_id`) | Re-list to get a current ID |
| 429 | Rate limited | Wait the `Retry-After` seconds in the message, then retry |

Quote the `request_id` when raising a ticket with Kaseya support.

## Gotchas

- **Rate limits are undocumented.** In a sweep across many customers, prefer
  one tenant-wide call with a filter (`status: "Failed"`) over one call per
  customer, and pause on a 429.
- **BackupIQ hides muted alerts by default.** `is_muted` defaults to `false`;
  pass `all` to include them.
- **The v1 Spanning tools are older shapes of the same data.** Use the v2 tools
  unless a field is missing there.
- **Only one host is documented** (`public-api.backup.net`). If a non-US tenant
  returns errors on every call, the region question is open with the vendor.

## Related Skills

- [backup-health-triage](../backup-health-triage/SKILL.md): the daily failure sweep
- [protection-coverage](../protection-coverage/SKILL.md): what each customer has protected
- [spanning-saas-backup](../spanning-saas-backup/SKILL.md): Microsoft 365 and Google Workspace backup

