Datto BCDR API Patterns

Status note

The MCP server (datto-bcdr-mcp) and SDK (@wyre-technology/node-datto-bcdr) are in development. This skill is reference documentation; the implementation will follow these patterns.

Overview

The Datto BCDR API (also known as the Datto Backup Portal API or "RESTful Reporting API") exposes the state of every SIRIS/Alto appliance and protected agent in a partner's fleet. Base URL:

https://api.datto.com/v1

Reference: <https://continuity.datto.com/help/Content/kb/DBMA/KB400000010980.htm>

This is a separate API from Datto RMM. Different keys, different signing scheme, different endpoint surface.

Authentication

Datto BCDR uses HMAC-SHA256 request signing with a public + private key pair, not bearer tokens.

Key issuance

1. Log into the Datto Partner Portal (partners.datto.com)
2. Settings → Integrations → API Keys → Create Key
3. Capture the public key and private key — the private key is shown once
4. (Optional) Restrict the key to specific appliances or read-only

Request signing

Every request includes three headers:

The signature input string is:

<METHOD> + "\n" + <URL_PATH> + "\n" + <TIMESTAMP> + "\n" + <REQUEST_BODY>

Body is the empty string for GET requests. Signed with the private key as the HMAC secret.

import { createHmac } from 'node:crypto';

function signRequest({ method, urlPath, body = '', publicKey, privateKey }) {
  const ts = Math.floor(Date.now() / 1000).toString();
  const stringToSign = `${method.toUpperCase()}\n${urlPath}\n${ts}\n${body}`;
  const signature = createHmac('sha256', privateKey).update(stringToSign).digest('hex');
  return {
    'X-Datto-API-Key': publicKey,
    'X-Datto-API-Timestamp': ts,
    'X-Datto-API-Signature': signature,
  };
}

Clock skew tolerance is 5 minutes. NTP-sync the host or expect 401s.

Endpoint surface

Pagination

Use _page (1-based) and _perPage (max 250). Responses include a pagination object:

{
  "items": [ /* ... */ ],
  "pagination": {
    "page": 1,
    "perPage": 250,
    "totalPages": 4,
    "totalItems": 877
  }
}

Screenshot verification

Screenshots are PNG bodies, retrieved by epoch timestamp from the screenshot list endpoint. Datto runs hourly screenshot verification against virtualized recovery points; the screenshot is the visual proof that the backup is bootable.

1. GET /bcdr/device/{sn}/asset/{agentId}/screenshot
   → list of {timestamp, status, errorMessage}
2. GET /bcdr/device/{sn}/asset/{agentId}/screenshot/{timestamp}
   → image/png body

For LLM display, base64-encode and embed; or store and link.

Rate limits

Datto BCDR throttles at 120 req/min per partner. Above that, expect HTTP 429 with Retry-After (seconds). Long-running list operations should batch — avoid blasting per-agent screenshot fetches in parallel.

Error handling

Gotchas

• Clock skew: 5 minutes max. Containerized clients must use NTP.
• Path canonicalization: The URL_PATH in the signature must match the request line exactly including query string ordering. Sort query params before signing.
• Body in signature: Always include the literal request body — even an empty string for GET.
• Distinct from Datto RMM: A user with Datto RMM API keys cannot call BCDR endpoints; different key types entirely.
• Status semantics: A "successful" backup can still have a failed screenshot verification. Always inspect both lastBackup and lastScreenshotVerification per agent for full health.

Related skills

Domain-specific skills for backups, screenshots, virtualization, and alerts will land alongside the MCP server build-out.