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.

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 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 und das Objekt version (running, latest, updateAvailable, channel, latestTag, publishedAt, checkError, maintenance und weitere). Beide Aufrufe brauchen die Berechtigung status:read. Die Felder stehen unter Integrations-API.

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. Für Maschinendaten nutzen Sie GET /api/v1/endpoints. Siehe Endpoint-Backup.