Integration API
Restow ships a documented REST API under /api/v1, with an OpenAPI description, in every edition from day one: it is not a paid add-on. It exists to connect Restow to the tools an MSP or IT department already runs: RMM, PSA and ticketing systems. See Reference → API reference for where the machine-readable description and the operational endpoints live.
What it covers
Section titled “What it covers”- Backup, restore and verify status, and the underlying jobs (with a server-sent-events stream for live progress).
- Protected objects: mailboxes, OneDrives and IMAP accounts, with their last snapshot.
- Storage targets and their state.
- Servers and clients backed up by the agent (
GET /api/v1/endpoints), see Servers and clients. - Archive status and evidence: intake per capture channel, hash-chain verification, retention and legal holds, and an evidence report for a period (see Archiving).
- The running version and whether an update is available, see Version and updates.
- A per-tenant directory: a clean listing of users and mailboxes, meant for handing to a PSA for billing or asset tracking.
- Webhooks, see below.
API keys and scopes
Section titled “API keys and scopes”Create keys under Integrations → API keys. Each key belongs to one tenant, has a name (shown in the key list and the audit log), an optional expiry (30/90/180/365 days, or none), and only the scopes it needs. Scopes are not implied by each other, so a key that changes protection also needs read access if it reads users too. The full set:
| Scope | Grants |
|---|---|
status:read |
Summary, storage, latest verify report, servers and clients (endpoints), running version. |
jobs:read |
Jobs with progress, failures and duration. |
items:read |
Protected objects with their last snapshot. |
users:read |
The user/mailbox directory, for PSA sync and billing. |
archive:read |
Archive status, capture channels, chain verification and the evidence report. |
restore:write |
Start backups and restores. |
verify:write |
Start verify runs (sampled test restores). |
users:write |
Include/exclude users from protection, e.g. on- and offboarding. |
webhooks:manage |
Create, change and delete this tenant’s webhooks. |
A key authenticates as Authorization: Bearer <key> and is rate-limited to 600 requests per 10 minutes. Restow shows the key’s value once, at creation: it stores only a fingerprint, so a lost key can’t be recovered, only revoked and replaced. Revoking is immediate and irreversible; the entry stays listed for the audit trail.
The Service Provider edition additionally offers provider keys: they work across every tenant the provider manages (requests name the tenant with an X-Restow-Tenant header), for a single integration point across all customers.
Servers and clients
Section titled “Servers and clients”GET /api/v1/endpoints lists the servers and clients that the Restow agent backs up (Endpoint backup), for an RMM’s asset list or per-machine billing. It needs the scope status:read, takes an optional profile=server or profile=client, and is not paged: the answer is { "items": [...], "total": n }. Every read is audited like the other reads. Each entry has:
| Field | Meaning |
|---|---|
id, hostname, displayName |
The machine. |
profile |
server or client. |
os, arch |
The system (linux, or darwin for macOS, today) and the CPU architecture (amd64 or arm64). |
agentVersion, status |
The version of the agent, and active or revoked. |
connection |
online when the agent was heard from within 15 minutes, otherwise offline, or never. |
lastSeenAt, lastBackupAt, lastSuccessAt |
The last contact, the end of the last backup run whatever its outcome, and the end of the last backup that produced a snapshot. |
readiness |
state (green, yellow, red, unverified or no_backup), checkedAt and overdue. A machine is green only after a restore test of its newest backup matched every sampled hash. |
attention |
Why the machine needs a look: silent, backup_overdue, last_backup_failed, restore_test_failed, repository_damaged or never_seen. |
createdAt |
When the machine was created in Restow. |
GET /api/v1/status also carries an endpoints object with the counts total, servers, clients, revoked, needingAttention and lastSuccessAt.
Version and updates
Section titled “Version and updates”GET /api/v1/status reports the running version and the opt-in update hint in a version object, so an RMM can mark outdated installations. Its fields: running, latest (the newest release of the channel, when the check ran), updateAvailable (null when that is not known), releaseUrl, updateCheck (disabled, pending, ok or failed), checkedAt, channel (stable or beta), latestTag (as published, for example v1.2.3), publishedAt, checkError (why the last check failed, for example rate_limited or not_found; null when it did not) and maintenance (an update that is announced or running through the updater, with phase, targetVersion and startsAt; null otherwise). The update check is off until an administrator turns it on, so updateCheck is disabled on a fresh installation. A status call never waits for the network. See Updates.
Why a job failed
Section titled “Why a job failed”Job objects carry the cause of a failure next to the plain errorMessage. failure holds a stable cause code (for example graph.consent_missing, graph.throttled, imap.auth_failed, storage.full, verify.hash_mismatch or unknown), its category, whether waiting alone may help (transient) or a manual retry makes sense (retryable), params (the missing permission, the host, the seconds to wait), redacted technical details for a support case, occurredAt, the step the run was in, the automatic retry state, the ordered steps to fix it and a docsUrl. It is null for a job that did not fail or that predates cause tracking. itemCauses lists the causes behind the failed items of a finished job, most frequent first (at most three). The job detail adds a failure to each failed item, and failureGroups, the failed items grouped by cause. See Failure explanations.
Webhooks
Section titled “Webhooks”Restow calls a URL you register when a chosen event happens, for example so a PSA opens a ticket when a backup fails. Events currently defined: job.failed, job.completed, verify.completed, plus a manual “send test event”. Each webhook has its own signing secret, shown once at creation (or after Rotate secret): every delivery is a JSON POST, signed as sha256=<HMAC-SHA-256 of the raw body> in the X-Restow-Signature header, with X-Restow-Event, X-Restow-Delivery and X-Restow-Attempt alongside it. Verify the signature (constant-time comparison) before trusting a request. A non-2xx response is retried at 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; HTTP 410 ends the delivery immediately. The delivery log keeps every attempt for about 30 days after it finishes, and a delivery can be replayed on demand.
The job.failed payload (data.job) carries the cause as failure: the stable code, whether waiting alone may help (transient) and the params a ticket needs. A failed run of a server or client raises job.failed too, with queue set to endpoint_backup or endpoint_restore and an additional data.endpoint (id, hostname, displayName, profile, os). A run that the agent had to interrupt because it restarted is not a failure and raises no webhook.
Webhook targets in loopback or private networks are refused unless the operator has allowed them (RESTOW_WEBHOOK_ALLOW_PRIVATE); link-local (cloud metadata) and other reserved ranges are always refused, regardless of that setting.
Auditing
Section titled “Auditing”Every read of user or backup data through the API, by a key or by the web interface, is written to the audit log, exactly the same way: who (or which key), when, what, for whom, and from which IP.