Unitrends API Patterns

Unitrends API Patterns

Status note

The MCP server (unitrends-mcp) and SDK (@wyre-technology/node-unitrends) are in development.

Overview

Unitrends Backup appliances expose a REST API on each appliance. Reference: https://github.com/unitrends/unitrends-api-doc/wiki

Base URL is per-appliance:

https://<appliance>/api

For multi-appliance MSPs, an MSP Console aggregates across appliances at:

https://<msp-console>/api

The MCP server takes the base URL as a credential field.

Anti-triggers

• Datto SIRIS/Alto appliances — Kaseya's other backup appliance line, reached through a central portal with HMAC-signed requests rather than a per-appliance session token; use datto-bcdr-api-patterns.
• SaaS backup for Microsoft 365, Google Workspace, or Salesforce — Unitrends protects assets behind an appliance, not cloud tenants; use spanning-api-patterns or datto-saas-protection-api-patterns.

Authentication

Session-token flow:

1. POST /api/login with body { "username": "...", "password": "..." }
2. Response: { "token": "...", "expires": <epochSeconds> }
3. Send on every call: Authorization: Bearer <token>
4. Token TTL: 60 minutes idle, sliding window

Re-auth on 401; wrap in single-flight mutex to avoid concurrent re-auth races.

Hierarchy

Appliance (the Unitrends host)
 └── Asset (a protected machine — VM, physical, NAS, M365 tenant)
      └── Asset Source (specific data type — VMware VM, file system, SQL DB)
           └── Backup Job
                └── Recovery Point (restore point)

When designing queries, always think appliance-first; assets are scoped to one appliance unless on the MSP Console.

Common endpoints

Pagination

Page-based:

Responses include total for the full result count.

Rate limits

Per-appliance limits depend on hardware tier; Unitrends doesn't publish them. Defensive defaults: cap concurrency at 2 per appliance, sustained 60 req/min. HTTP 503 typically signals an appliance under load — back off for 30 seconds.

Error handling

Gotchas

• Self-signed certs: On-prem Unitrends appliances often ship with self-signed certs. The MCP server should accept a verifyTls credential field; default true, allow false for trusted internal networks.
• MSP Console vs appliance API drift: The MSP Console aggregates a subset of endpoints. Asset-level operations (mount, restore) typically must target the appliance directly, not the console.
• Asset IDs are appliance-scoped: An asset ID 123 on appliance A is not the same asset on appliance B. Always carry applianceId alongside.
• Job status semantics: success ≠ "data is recoverable". A job can complete successfully with a degraded recovery point. Inspect both status and verifyState for full health.

Related skills

When the build-out lands, expect domain skills for: appliances, assets, jobs, recovery-points, replication.