API-Referenz

Wofür die API da ist und wie Sie Schlüssel und Webhooks verwalten, steht unter Integrations-API. Diese Seite ist der kurze technische Verweis.

OpenAPI-Beschreibung

Die REST-API liegt unter /api/v1; ihre OpenAPI-Beschreibung wird aus denselben Zod-Schemas erzeugt, gegen die die API Anfragen validiert, und ausgeliefert unter:

GET /api/v1/openapi.json

Richten Sie ein beliebiges OpenAPI-fähiges Werkzeug (Swagger UI, Postman, ein SDK-Generator, …) gegen diese URL Ihrer eigenen Installation, um den vollständigen, exakten Vertrag Endpunkt für Endpunkt zu erhalten. Diese Dokumentationsseite dupliziert ihn nicht von Hand, da ein von Hand kopierter Vertrag vom laufenden Server abweichen würde.

info.version dieses Dokuments ist die Version des Vertrags (seit 0.4.7 1.7.0; 1.6.0 kam mit 0.4.5 und 1.5.0 mit 0.4.2, siehe Integrations-API), und x-restow-build der laufende Build. Seit 0.4.7 umfasst der Status orphaned eines Objekts auch Objekte, die noch an der Quelle stehen, aber nicht mehr gesichert werden (deaktiviertes oder unlizenziertes Konto, von Microsoft gesperrt), unterschieden durch das neue statusReason; prüfen Sie es, bevor Sie orphaned als gelöschtes Konto behandeln.

Authentifizierung

• API-Schlüssel und Provider-Schlüssel (siehe Integrations-API): Authorization: Bearer <Schlüssel>, begrenzt auf 600 Anfragen je 10 Minuten je Schlüssel.
• Die Web-Oberfläche selbst authentifiziert sich mit einem Sitzungs-Cookie (better-auth); dieser Sitzungsmechanismus ist nicht für Integrationen Dritter gedacht, nutzen Sie stattdessen einen API-Schlüssel.

Live-Fortschritt

Der Fortschritt eines Jobs ist als Server-Sent-Events-Stream verfügbar: GET /api/v1/jobs/{id}/events.

Server, Clients, Freigaben und Versionen

GET /api/v1/endpoints listet die Server und Clients auf, die der Restow-Agent sichert. GET /api/v1/status enthält Zahlen dazu, Zahlen zu Proxmox-VE-Gästen (guests) und, seit 0.4.0 (Vertrag 1.4.0), zu Freigaben (fileShares) sowie das Objekt version (running, commit, latest, updateAvailable, channel, latestTag, publishedAt, checkError, maintenance und weitere). Beide Aufrufe brauchen die Berechtigung status:read. Die Felder stehen unter Integrations-API und Freigaben und belegte Bytes. physicalBytes von GET /api/v1/status und GET /api/v1/storage enthalten seit 0.4.1 die restic-Repositories. Seit 0.4.5 (Vertrag 1.6.0) ist lastSuccess.groups des Status die neueste wiederherstellbare Sicherung eines Microsoft-365-Gruppenpostfachs, die Objektart group ein Wert von ObjectKind, und version.releasedAt das Release-Datum des laufenden Builds (Vertrag 1.6.0). Seit 0.4.7 (Vertrag 1.7.0) meldet der Status Proxmox-VE-Gäste, die eine Administration von der Sicherung ausgeschlossen hat, als guests.excluded, und die Zusammenfassung der Bereitschaft von Status und GET /api/v1/verify/latest trägt toConfirm, die Objekte, die nicht mehr gesichert werden und auf eine Bestätigung warten (Vertrag 1.7.0).

Geschützte Postfächer

GET /api/v1/usage liefert die geschützten Postfächer der Installation, insgesamt und je Mandant (ein OneDrive zählt nicht doppelt, importierte Postfächer, SharePoint-Websites und, seit 0.4.5, Microsoft-365-Gruppenpostfächer zählen nicht). Der Aufruf ist für Provider-Administrationen gedacht, die in der Web-Oberfläche angemeldet sind, und liefert, was die Karte Geschützte Postfächer im Reiter Status der Übersicht zeigt. Nichts begrenzt diese Zahlen; sie dienen Ihrer eigenen Übersicht und Abrechnung. Seit 0.4.7 multipliziert die Kachel Preis je Monat in der Übersicht eines Mandanten dessen Zahl mit den Preisen, die ein Inhaber unter Installation → Preise eingetragen hat (Mandantenfähigkeit). Siehe Lizenz und Editionen.

Routen der Weboberfläche (seit 0.4.2)

Die Weboberfläche ruft unter /api/v1 mehr Routen auf, als die Integrations-API beschreibt. Sie gehören nicht zum Vertrag: Sie brauchen eine angemeldete Sitzung (ein Provider-Benutzer nennt den Mandanten mit X-Restow-Tenant), ein API-Schlüssel erreicht sie nicht, sie stehen nicht in openapi.json, und sie können sich mit der Oberfläche ändern. Sie sind hier aufgeführt, weil die Schaltflächen sie aufrufen und das Audit-Log festhält, was sie tun. Die seit 0.4.2 hinzugekommenen:

Route	Was sie tut	Wer
GET /api/v1/storage/destination	Nennt das wirksame primäre Repository des Mandanten: sein eigenes primäres (Name, Art, Pfad oder Bucket) oder den Installationsstandard (dessen Pfad nur für Provider-Administratoren). Es ist die Zeile „Sicherungen landen in“ und sagt, ob die eigene Platte des Servers das Ziel ist (Wo Sicherungen landen).	Mandanten-Administratoren
POST /api/v1/pve/guests/:id/repository/reset	Repository zurücksetzen bei einem Container. Body { "confirmName": "<Name des Gasts>" }; braucht eine frische Anmeldung. Jeder Sicherungsstand des Containers wird nicht verfügbar, die nächste Sicherung beginnt eine neue Kette. Im Audit-Log als pve.repository.reset.	Mandanten-Administratoren
POST /api/v1/pve/guests/:id/verify	Jetzt prüfen für den neuesten Sicherungsstand eines Gasts. Antwortet 202.	Mandanten-Administratoren
POST /api/v1/pve/verify-unverified	Alle ungeprüften prüfen: der neueste Sicherungsstand jedes Gasts, den noch keine Prüfung gelesen hat und auf den keine wartet. Antwortet 202 mit der Zahl der eingereihten.	Mandanten-Administratoren
GET /api/v1/settings/pve, PUT /api/v1/settings/pve	Die Proxmox-VE-Einstellungen der Installation, heute verifyAfterBackup (jeden neuen Sicherungsstand direkt nach der Sicherung prüfen, standardmäßig an). Lesen kann jeder Provider-Administrator, ändern ein Inhaber. Im Audit-Log als settings.pve.updated.	Provider
GET /api/v1/snapshots/:id/calendar	Der Kalender eines Postfach-Sicherungsstands in einem Fenster (from und to, höchstens 3660 Tage auseinander; path ist standardmäßig calendar; entryId öffnet eine Serie), jede Serie in ihre Termine aufgefaltet. Im Audit-Log als snapshot.calendar.read.	Mandantenbenutzer, für das, was sie sehen dürfen
GET /api/v1/snapshots/people	Eine Seite der linken Spalte des Restore-Explorers: section (people oder sites), q (Namen, Adressen und Konto-IDs), kind (mailbox, onedrive, imap oder site), limit (standardmäßig 50, bis 200) und after (der Cursor next der vorigen Seite), der Eintrag der angemeldeten Person zuerst. Die Snapshot-Objekte tragen ownerKey und ownerName.	Mandantenbenutzer, für das, was sie sehen dürfen

Die Schaltflächen zum Stoppen und Aktualisieren nutzen eigene Routen: POST /api/v1/pve/guests/:id/cancel, POST /api/v1/pve/nodes/:id/queue/pause, .../queue/resume und .../queue/cancel, POST /api/v1/pve/queue/cancel und POST /api/v1/pve/nodes/:id/update für Proxmox VE, PUT /api/v1/pve/guests/:id/restow-server zum Markieren der VM des Restow-Servers selbst, POST /api/v1/endpoints/:id/cancel und POST /api/v1/endpoints/:id/update für Rechner und PUT /api/v1/settings/time-zone für die Zeitzone der Installation. Seit 0.4.3 ruft Knoten und Agenten jetzt aktualisieren POST /api/v1/updates/fleet/update-now auf (ein Administrator mit allen Mandanten; im Audit-Log als update.fleet_started mit manual: true), und das Proxmox-VE-Inventar GET /api/v1/pve meldet für jeden Knoten neben seiner helperVersion die offeredVersion (das restow-pve-Release, das der Server anbietet) und outdated. Der lastVerify.state eines Gasts kann seit 0.4.3 yellow sein, wobei notChecked sagt, warum die Restore-Prüfung nicht laufen konnte.

Archiv-Erfassung (seit 0.4.4)

Die Archiv-Erfassung seit 0.4.4 (Graph, IMAP-Archivierung, weitergeleitete Kopien; siehe Archivierung) bringt Routen und Felder derselben Art: für die Weboberfläche, nicht Teil des Vertrags (1.5.0 bleibt unverändert), nicht in openapi.json, von einem API-Schlüssel nicht erreichbar. Sie brauchen eine angemeldete Mandanten-Administration und eine Lizenz Business oder Service Provider, wo die Erfassung eine braucht.

Route oder Feld	Was es tut
GET /api/v1/archive/capture	Der Zustand jedes Erfassungswegs: ob die Edition ihn enthält, die Ströme nach Status (pending, backfilling, live, paused, disabled, error), wie neue Mail bemerkt wird (benachrichtigt oder im Intervall geprüft, mit dem Grund wie graph.notification_url_unavailable oder imap.idle_budget), die Zähler für 24 Stunden und 7 Tage und der Fortschritt der Übernahme. jobs listet die Mail-Jobs, deren IMAP- oder Google-Workspace-Konten auf einen Erfassungsweg warten.
GET /api/v1/archive/capture/mailboxes	Die Erfassung je Postfach, gefiltert nach Weg und Status, seitenweise.
POST /api/v1/archive/capture/mailboxes/:objectId/resync	Neu abgleichen: liest das Postfach beim nächsten Durchlauf vollständig neu. Antwortet 202; auditiert als archive.capture.resync_requested.
GET /api/v1/archive/capture/holds	Je Microsoft-365-Quelle, ob ein Hold bestätigt ist, und checks: die Befehle für Exchange Online und Security & Compliance PowerShell, die nur lesen und Holds und Aufbewahrungsrichtlinien prüfen.
PUT /api/v1/archive/capture/holds/:sourceId	Body { "status": "confirmed" } oder { "status": "unknown" }: die Bestätigung einer Administration, dass eine Aufbewahrungsrichtlinie oder ein Litigation Hold gelöschte Mail im Mandanten hält, oder ihre Rücknahme. Auditiert als archive.hold.confirmed und archive.hold.unconfirmed. Restow kann es nicht prüfen.
GET /api/v1/archive/forwarding	Die IMAP-Konten, deren Job die Weiterleitung gewählt hat, ihre Archivadressen und die weitergeleiteten Kopien der letzten 7 Tage. Es stellt nichts aus.
POST /api/v1/archive/forwarding/:objectId/address	Stellt die Archivadresse des Kontos aus, einmalig. Auditiert als archive.forward.address_created.
POST /api/v1/archive/forwarding/:objectId/rotate	Ersetzt die Adresse; die alte wird sofort abgewiesen. Auditiert als archive.forward.address_rotated, nur mit Fingerabdruck.
GET /api/v1/archive/journal	Nennt jetzt auch firstReportAt, den ersten Journal-Report, der angekommen ist.
GET /api/v1/archive/search	includeSuperseded=true listet auch die Erfassungen, die ein stärkerer Weg ersetzt hat; ohne es sind sie ausgeblendet. Das Elementdetail verweist in beide Richtungen (supersededBy, captures). Der Export der aktuellen Suche trägt es als includeSuperseded im Suchfilter.
archiveCapture eines Mail-Jobs	Die Erfassungswege je Art von Postfach (m365: graph, journal; imap und google: sync, forward), beim Anlegen, Ändern und Lesen von /api/v1/backup-jobs. Ein Job, der archiviert, ohne dass für eine Art, die er abdeckt, ein Weg gewählt ist, wird mit 422 archive_capture_no_way abgelehnt. Siehe So gelangen E-Mails ins Archiv.
captureKind eines Mitglieds oder Kandidaten	m365, google, imap oder imap_microsoft: die Art des Postfachs, die bestimmt, welche Wege der Editor anbietet.
mailSourceKinds von GET /api/v1/backup-jobs/defaults?kind=mail	Die Arten der aktiven Mail-Objekte des Mandanten.
archiveIdle von PATCH /api/v1/sources/:id	auto (die Vorgabe) oder off für eine IMAP-Quelle: off ist Nur in Abständen prüfen, keine Verbindung bleibt offen.

Öffentliche Hooks. Zwei Routen sind ohne Sitzung für das Internet offen, nur für Microsoft Graph: POST /api/v1/hooks/graph/notifications und POST /api/v1/hooks/graph/lifecycle. Das Validierungs-Token eines neuen Abonnements wird zurückgegeben, alles andere mit 202 beantwortet, nur eine Benachrichtigung, deren clientState zum gespeicherten SHA-256 des Abonnements passt, zählt, und eine Benachrichtigung trägt keine Mail, nur die Tatsache, dass eine angekommen ist. Der Body ist auf 1 MiB begrenzt, und die Routen antworten mit 404, solange die Edition die Erfassung aus dem Postfach nicht enthält. Sie sind nicht für Integrationen; siehe Netzwerk und Ports.

Routen der Weboberfläche (seit 0.4.5)

Wie die seit 0.4.2 gehören die Routen hinter den Schaltflächen, die mit 0.4.5 kamen, nicht zum Vertrag: Sie brauchen eine angemeldete Sitzung (ein Provider-Benutzer nennt den Mandanten mit X-Restow-Tenant), ein API-Schlüssel erreicht sie nicht, sie stehen nicht in openapi.json, und sie können sich mit der Oberfläche ändern.

Route	Was sie tut	Wer
POST /api/v1/backup-jobs/:id/cancel	Stoppen bei einem Job der Liste Mail & SaaS oder Server & Clients: zieht jede wartende Sicherung eines Mail-, Rechner-, Freigaben- oder Kopierjobs zurück und bittet jede laufende, anzuhalten, in einer Anfrage. Auditiert als backup_job.run_cancelled am Job und, bei Rechnern, je Rechner (endpoint.backup.cancelled).	Mandanten-Administratoren und Provider-Rollen, die bedienen dürfen; in der öffentlichen Demo gesperrt
POST /api/v1/pve/jobs/:id/run	Jetzt starten bei einem Proxmox-VE-Job: reiht eine Sicherung jedes Gasts ein, den der Job umfasst, wie sein Zeitplan es täte, ohne den Zeitplan zu verschieben. Gäste, die schon eine wartende Sicherung haben, auf einem Knoten ohne restow-pve liegen oder die unbestätigte VM des Restow-Servers sind, werden ausgelassen und gezählt. Auditiert als pve.job.run_requested.	Dieselben
POST /api/v1/pve/jobs/:id/cancel	Stoppen bei einem Proxmox-VE-Job: zieht seine wartenden Sicherungen zurück und bittet seine laufenden, anzuhalten. Auditiert als pve.job.cancelled.	Dieselben
POST /api/v1/endpoints/:id/remove	Aus Restow entfernen für einen gesperrten Rechner. Body { "mode": "delete" | "expire", "confirmHostname": "<hostname>" }; braucht eine frische Anmeldung. Auditiert als endpoint.removed. Die Antworten (409 endpoint-not-revoked, endpoint-removal-legal-hold, endpoint-removal-suspicion-hold, endpoint-removal-never-expires; 422 endpoint-confirm-hostname) stehen unter Deinstallation und erneute Anmeldung.	Mandanten-Administratoren
GET /api/v1/endpoints/removals	Die entfernten Rechner, deren Sicherungen noch nicht gelöscht sind, mit dem Datum, der Hold oder der Sperre des Speichers. Es ist die Liste unter dem Inventar.	Mandanten-Administratoren

Seit 0.4.6 antworten die Routen, die die Sicherungen eines Rechners lesen (GET /api/v1/endpoints/:id, /snapshots, /browse, /downloads und POST .../repository-password), auch für einen entfernten Rechner, bis seine Sicherungen gelöscht sind, auditiert wie bei einem gesperrten. Das Wiederherstellen auf den Rechner und jede andere Aktion an ihm antworten 404; sind die Sicherungen gelöscht, ist er für jeden Leser weg.

Routen der Weboberfläche (seit 0.4.7)

Wie die seit 0.4.2 und 0.4.5 gehören die Routen hinter den Schaltflächen, die seit 0.4.7 neu sind, nicht zum Vertrag (1.7.0 fügt nur Felder und Werte hinzu, siehe Integrations-API): Sie brauchen eine angemeldete Sitzung (ein Provider-Benutzer nennt den Mandanten mit X-Restow-Tenant), ein API-Schlüssel erreicht sie nicht, sie stehen nicht in openapi.json, und sie können sich mit der Oberfläche ändern.

Route	Was sie tut	Wer
POST /api/v1/directory/objects/:id/inactive/confirm	Ja, beabsichtigt für ein Objekt, das nicht mehr gesichert wird (siehe Objekte, die nicht mehr gesichert werden). Der Body kann eine note (1 bis 1000 Zeichen) für das Audit-Log tragen; die Oberfläche fragt keine ab. Auditiert als directory.inactive.confirmed.	Mandanten-Administratoren und Provider-Rollen, die konfigurieren dürfen
POST /api/v1/directory/objects/inactive/confirm	Dasselbe für mehrere Objekte des Mandanten: { "objectIds": [...] } oder { "filter": {...} } (der Filter der Liste), höchstens 1000, mit derselben optionalen note. Bestätigt werden nur Objekte, die noch auf eine Bestätigung warten. Auditiert als directory.inactive.bulk_confirmed.	Wie oben
GET /api/v1/directory/objects	Nimmt zusätzlich die Filter to_confirm und confirmed für den Status nicht mehr gesicherter Objekte und liefert statusReason, inactiveSince, statusConfirmedAt und statusConfirmedBy (eine Adresse, api-key:<id>, migration oder excluded).	Mandanten-Administratoren und Provider-Rollen, die ansehen dürfen
PATCH /api/v1/sources/:id/own-app/expiry	Trägt das Ablaufdatum des Client-Secrets der eigenen App einer Quelle ein, ändert oder entfernt es ({ "secretExpiresAt": "2027-03-01" } oder null), ohne das Secret erneut einzugeben. Auditiert als source.own_app.expiry_updated. Ein Zertifikat hat sein eigenes Datum.	Mandanten-Administratoren und Provider-Rollen, die konfigurieren dürfen
PUT /api/v1/pve/guests/:id/excluded	Von der Sicherung ausschließen oder Wieder einschließen für einen Proxmox-VE-Gast: Body { "excluded": true } oder false, Antwort 204. Auditiert als pve.guest.excluded mit der Zahl der zurückgezogenen wartenden Sicherungen. Zweimal ausschließen ändert nichts. GET /api/v1/pve meldet excludedAt und excludedBy je Gast. Eine Sicherung oder eine Job-Zuordnung eines ausgeschlossenen Gasts wird mit 409 urn:restow:problem:pve-guest-excluded abgelehnt.	Mandanten-Administratoren und Provider-Rollen, die konfigurieren dürfen
GET /api/v1/settings/pricing, PUT /api/v1/settings/pricing	Die Monatspreise hinter der Preis-Kachel: currency (EUR, CHF, USD oder GBP), mailboxPrice, storagePrice und storageUnit (GB oder TB), jeder Preis mit höchstens vier Nachkommastellen oder null. Gelesen von jedem Provider-Administrator mit allen Mandanten, geändert vom Inhaber. Auditiert als settings.pricing.updated mit den Werten davor und danach. Mandanten-Benutzer sehen sie nie.	Provider

Betriebs-Endpunkte (außerhalb von /api/v1)

Endpunkt	Zweck
GET /healthz	Der Prozess läuft.
GET /readyz	Der Prozess ist bereit, Anfragen zu bedienen (Abhängigkeiten wie die Datenbank sind erreichbar).

Diese sind absichtlich unauthentifiziert und unversioniert, damit ein Load Balancer oder Container-Orchestrator sie ohne Zugangsdaten abfragen kann.

Endpunkte für den Agent (außerhalb von /api/v1)

Endpunkt	Zweck
/agent/v1/*	Die API des Restow-Agents: Enrollment, Konfiguration, Heartbeat, Läufe, Agent-Update. Das Enrollment nutzt ein Einmal-Token, jeder andere Aufruf das eigene Secret des Endpunkts; ein API-Schlüssel ist nicht beteiligt.
/agent/restic/<Endpoint-ID>/	Das restic-Repository eines Endpoints. Für den Agent ist es nur anhängend.
/install/*	Die Installationsskripte und die Binärdateien von Agent und restic mit ihren SHA256SUMS, für den Installationsbefehl.

Sie werden unter derselben öffentlichen Adresse wie die Web-Oberfläche ausgeliefert und vom Agent und vom Installationsbefehl genutzt, nicht von Integrationen. Die Runner der Sicherung von Freigaben nutzen stattdessen Pfade unter /internal/, die der Web-Edge nie weiterleitet: Sie sind nur im internen Docker-Netz runners erreichbar. Für Maschinendaten nutzen Sie GET /api/v1/endpoints. Siehe Endpoint-Backup.