API-Referenz¶

Die vollständige Referenz ist das OpenAPI-Schema, das die API selbst erzeugt. Es liegt im API-Container und ist über die Domain nicht erreichbar — wie du es exportierst, steht in der API-Übersicht.

Die Liste unten nennt die Endpoints, die man für Automationen am häufigsten braucht. Alle Pfade beginnen mit https://deine-domain.tld.

Kategorisierte Endpoints¶

Auth¶

POST /api/v1/auth/login — email + password (optional remember); bei 2FA kommt pending_token
POST /api/v1/auth/2fa/verify — zweiter Faktor mit pending_token
POST /api/v1/auth/2fa/webauthn/begin — Passkey-Challenge für den Login
POST /api/v1/auth/refresh — gültiges Access-Token gegen ein neues tauschen; endet an der absoluten Sitzungs-Frist
POST /api/v1/auth/logout — beendet die Cookie-Sitzung der Web-App
GET /api/v1/auth/me
PUT /api/v1/auth/preferences
POST /api/v1/auth/change-password — meldet alle anderen Sitzungen und Tokens ab; optional revoke_api_tokens: true widerruft zusätzlich alle API-/KI-Zugänge des Kontos
GET /api/v1/auth/step-up/status · POST /api/v1/auth/step-up — Identität für heikle Aktionen bestätigen
GET /api/v1/auth/sessions · DELETE /api/v1/auth/sessions/{session_id} · POST /api/v1/auth/sessions/revoke-others (optional {"revoke_api_tokens": true})
GET /api/v1/auth/sso/providers · GET /api/v1/auth/sso/{provider_id}/start — SSO-Anmeldung (OIDC, Vorschau-Funktion)

Heikle Aktionen antworten mit 403 und {"detail": {"code": "STEP_UP_REQUIRED", …}}, bis die Identität frisch bestätigt wurde (siehe Auth-Flow). Objekte fremder Tenants antworten mit 404, nie mit 403.

Collector-API-Keys (POST /api/v1/collectors/{collector_id}/regenerate-key) und Agent-Tokens (POST /api/v1/hosts/{host_id}/agent-token) sind eigene Auth-Mechanismen für Collectors/Agents — keine Benutzer-Anmeldung, siehe Auth-Flow.

Benutzer, Rollen, Teams, Tenants¶

GET/POST /api/v1/users/ · PATCH/DELETE /api/v1/users/{user_id}
GET/PUT /api/v1/users/{user_id}/access — Tenant-Zugriff und Rolle je Tenant
POST /api/v1/users/{user_id}/password · POST /api/v1/users/{user_id}/2fa/reset
GET/POST /api/v1/roles/ · GET/PATCH/DELETE /api/v1/roles/{role_id} · GET /api/v1/roles/permissions
GET/POST /api/v1/teams/ · GET/PATCH/DELETE /api/v1/teams/{team_id}
GET/POST /api/v1/tenant-groups/ · PATCH/DELETE /api/v1/tenant-groups/{group_id} · PUT /api/v1/tenant-groups/membership
GET/POST /api/v1/tenants/ · PATCH/DELETE /api/v1/tenants/{tenant_id}

Hosts und Checks¶

GET /api/v1/hosts/ — limit (max. 500), offset, tenant_id, include_inactive; Gesamtzahl in X-Total-Count
POST /api/v1/hosts/search — Filter-Abfrage (Profile, Tenants, Status, Hostname-Regex, Suchtext …)
POST /api/v1/hosts/
GET /api/v1/hosts/{host_id}
PATCH /api/v1/hosts/{host_id}
DELETE /api/v1/hosts/{host_id} — in den Papierkorb
POST /api/v1/hosts/{host_id}/agent-token
GET /api/v1/host-services/ · POST /api/v1/host-services/
GET/PATCH/DELETE /api/v1/host-services/{host_service_id}
POST /api/v1/host-services/{host_service_id}/check-now
POST /api/v1/host-services/bulk-update · POST /api/v1/host-services/bulk-delete

Status und Bestätigen (ACK)¶

GET /api/v1/status/summary · GET /api/v1/status/errors · GET /api/v1/status/host/{host_id}
POST /api/v1/status/acknowledge/{service_id} · DELETE /api/v1/status/acknowledge/{service_id}
POST /api/v1/status/bulk-acknowledge · POST /api/v1/status/bulk-unacknowledge
GET /api/v1/acknowledgements/ — Liste der Bestätigungen
GET /api/v1/history/{service_id} — Verlauf eines Checks

Profile¶

GET /api/v1/profiles/
POST /api/v1/profiles/
GET /api/v1/profiles/{profile_id}
PUT /api/v1/profiles/{profile_id}
DELETE /api/v1/profiles/{profile_id}
GET /api/v1/profiles/{profile_id}/checks · POST /api/v1/profiles/{profile_id}/checks
GET /api/v1/profiles/{profile_id}/usage
POST /api/v1/profiles/{profile_id}/clone
GET /api/v1/profiles/{profile_id}/export — Profil als Bundle (inkl. referenzierter Scripts)
POST /api/v1/profiles/import — Bundle importieren
POST /api/v1/profiles/{profile_id}/apply
GET /api/v1/community/browse — Vesana-Bibliothek durchsuchen
GET /api/v1/community/profile/{community_id} — Detail
POST /api/v1/community/import — Profil aus der Bibliothek installieren
GET /api/v1/community/updates — Update-Check für installierte Profile
GET /api/v1/community/update/{profile_id}/preview — Diff-Vorschau
POST /api/v1/community/update/{profile_id} — Update übernehmen (Super-Admin)

Discovery + SNMP¶

POST /api/v1/discovery/network-scan
GET /api/v1/discovery/scans · GET /api/v1/discovery/scans/{scan_id}
GET /api/v1/discovery/results
POST /api/v1/discovery/results/{result_id}/add
POST /api/v1/discovery/results/bulk-add
POST /api/v1/discovery/snmp-walk
GET /api/v1/discovery/snmp-walk/{walk_id}
POST /api/v1/discovery/snmp-walk/{walk_id}/apply

Alert-Regeln + Kanäle¶

GET /api/v1/alert-rules/ · POST /api/v1/alert-rules/
GET/PATCH/DELETE /api/v1/alert-rules/{rule_id}
POST /api/v1/alert-rules/{rule_id}/test
POST /api/v1/alert-rules/probe-alert — Probealarm durch die echte Kette
GET /api/v1/notifications/ · POST /api/v1/notifications/ — Benachrichtigungskanäle
GET/PATCH/DELETE /api/v1/notifications/{channel_id}
POST /api/v1/notifications/{channel_id}/test
GET /api/v1/notifications/log — Versandprotokoll

Die Listen unter /alert-rules/ und /notifications/ nehmen q, limit, offset und liefern X-Total-Count.

Wartungsfenster¶

GET /api/v1/downtimes/
POST /api/v1/downtimes/ — für einen Host, mehrere Hosts (host_ids) oder einen Check (service_id)
POST /api/v1/downtimes/bulk — mehrere Checks auf einmal
PATCH /api/v1/downtimes/{downtime_id}
DELETE /api/v1/downtimes/{downtime_id} · DELETE /api/v1/downtimes/batch/{batch_id}

Logs¶

POST /api/v1/logs/search
GET /api/v1/logs/stream — SSE
GET/POST /api/v1/logs/sources · PATCH/DELETE /api/v1/logs/sources/{source_id}

Log-Alert-Regeln gibt es nicht mehr (weder UI noch API) — Log-Alarme laufen über Eventlog-/Script-Checks und normale Alert-Regeln.

Dashboards¶

GET /api/v1/dashboards/ · POST /api/v1/dashboards/
GET/PUT/PATCH/DELETE /api/v1/dashboards/{dashboard_id}
POST /api/v1/dashboards/{dashboard_id}/duplicate
GET /api/v1/dashboards/{dashboard_id}/versions · POST /api/v1/dashboards/{dashboard_id}/restore/{version}

Berichte und SLA (Vorschau-Funktion „Reports (PDF + SLA)")¶

GET /api/v1/sla/services/{service_id}/sla
GET /api/v1/sla/tenants/{tenant_id}/sla-report — start, end (ISO-Zeitpunkte; Standard: letzte 30 Tage)
POST /api/v1/reports/generate · POST /api/v1/reports/preview
GET/POST /api/v1/reports/schedules

Wiki (Vorschau-Funktion) + KI¶

GET /api/v1/wiki/articles · POST /api/v1/wiki/articles
GET /api/v1/wiki/search?q=...
POST /api/v1/ai/chat
POST /api/v1/ai/chat/stream — SSE
POST /api/v1/ai/analyze/{service_id}
GET /api/v1/ai/status
GET/PUT /api/v1/ai/config
GET /api/v1/ai/models
POST /api/v1/ai/models/pull
POST /api/v1/ai/models/delete
POST /api/v1/ai/test-connection
GET /api/v1/ai/conversations · GET/PATCH/DELETE /api/v1/ai/conversations/{conversation_id}

Administration¶

GET /api/v1/admin/backups · POST /api/v1/admin/backups · POST /api/v1/admin/backups/{backup_id}/restore
GET /api/v1/admin/health/snapshot
GET /api/v1/admin/licence · GET /api/v1/admin/licence/status
GET /api/v1/admin/preview-features · PUT /api/v1/admin/preview-features/{key}

Im Split-Container-Modus sind die Endpoints der Administration (die meisten unter /api/v1/admin/…, dazu Rollen, Teams und Änderungen an Benutzern) nur über den Admin-Host erreichbar; auf dem Benutzer-Host antworten sie mit 404 und ADMIN_HOST_REQUIRED.

Audit-Log + Papierkorb¶

GET /api/v1/audit/ — Filter action, target_type, target_id, host_id, actor_email, search, category, created_from, created_to; limit (max. 500), offset
GET /api/v1/trash/summary
GET /api/v1/trash/{trash_type}
POST /api/v1/trash/{trash_type}/{item_id}/restore
DELETE /api/v1/trash/{trash_type}/{item_id} — endgültig löschen

Push (Web Push)¶

GET /api/v1/push/vapid-public-key
POST /api/v1/push/subscriptions — Browser-Abo des angemeldeten Benutzers anlegen
GET /api/v1/push/subscriptions/mine · PATCH/DELETE /api/v1/push/subscriptions/mine/{abo_id}
POST /api/v1/push/test

Die frühere native App und ihre push-tokens-Endpunkte sind entfernt.

Weitere¶

GET /api/v1/jump/search?q= — Schnellsuche (respektiert Tenant und Berechtigungen)
GET/POST /api/v1/credential-sets/ · PATCH/DELETE /api/v1/credential-sets/{set_id} — Zugangsdaten-Sets (Geheimnisse kommen nie zurück)
POST /api/v1/scripts/declaration · POST /api/v1/scripts/resolve · GET /api/v1/scripts/{script_id}/usage

Agent und Collector¶

Diese Wege benutzen Agent-Token bzw. Collector-Key, nicht das Benutzer-Token:

POST /receiver/api/v1/results — Check-Ergebnisse einliefern (X-API-Key oder X-Agent-Token)
POST /receiver/api/v1/logs/ingest — Log-Einlieferung
POST /api/v1/agent/heartbeat · GET /api/v1/agent/config
GET /api/v1/config/collector/{collector_id}

Antwort-Codes¶

Code	Bedeutung
200 / 201 / 202 / 204	Erfolg
400	Fehlerhafte Anfrage
401	Nicht angemeldet oder Token abgelaufen/widerrufen
403	Angemeldet, aber keine Berechtigung — oder `STEP_UP_REQUIRED`
404	Ressource nicht gefunden / nicht in deinem Tenant-Scope / Vorschau-Funktion nicht freigeschaltet
409	Konflikt (z. B. doppelter Hostname)
422	Validierung gescheitert (Detail im Body)
429	Rate-Limit
500	Server-Fehler
503	Dienst nicht verfügbar (z. B. Ersteinrichtung noch nicht abgeschlossen)