API-Referenz¶

Die vollständige API-Referenz wird aus dem FastAPI-OpenAPI-Schema generiert.

Live-Schema¶

Auf jeder Vesana-Instanz unter:

https://deine-domain.tld/openapi.json    — Schema (JSON)
https://deine-domain.tld/docs            — Swagger-UI
https://deine-domain.tld/redoc           — Redoc

Swagger-UI ist interaktiv: Endpoints aufklappen, Test-Anfragen direkt mit eingeloggtem Token absetzen.

Kategorisierte Endpoints¶

Auth¶

POST /api/v1/auth/login — Benutzername + Passwort (optional remember); bei 2FA folgt challenge_token
POST /api/v1/auth/2fa/verify
POST /api/v1/auth/refresh — rotiert das Refresh-Token; die Kette endet spätestens an der absoluten Sitzungs-Frist
POST /api/v1/auth/logout — beendet die Sitzung serverseitig
GET /api/v1/auth/me
PUT /api/v1/auth/preferences
GET /api/v1/auth/sso/{provider}/start — SSO-Anmeldung (OIDC)
POST /api/v1/auth/change-password — meldet alle anderen Sitzungen ab

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

Collector-API-Keys (/collectors/{id}/...) und Agent-Tokens (/hosts/{id}/agent-token) sind eigene Auth-Mechanismen für Collectors/Agents — kein User-API-Auth, siehe Auth-Flow.

Hosts und Services¶

GET /api/v1/hosts/
POST /api/v1/hosts/
GET /api/v1/hosts/{id}
PATCH /api/v1/hosts/{id}
DELETE /api/v1/hosts/{id}
POST /api/v1/host-services/
PATCH /api/v1/host-services/{id}
DELETE /api/v1/host-services/{id}
POST /api/v1/host-services/{id}/ack
DELETE /api/v1/host-services/{id}/ack

Profile¶

GET /api/v1/profiles/
POST /api/v1/profiles/
GET /api/v1/profiles/{id}
PATCH /api/v1/profiles/{id}
DELETE /api/v1/profiles/{id}
GET /api/v1/profiles/{id}/usage
POST /api/v1/profiles/{id}/clone
GET /api/v1/profiles/{id}/export — Profil als Bundle (inkl. referenzierter Scripts)
POST /api/v1/profiles/import — Bundle importieren
POST /api/v1/profiles/{id}/apply
GET /api/v1/community/browse — Community-Hub durchsuchen
GET /api/v1/community/profile/{id} — Community-Detail
POST /api/v1/community/import — aus dem Hub importieren
GET /api/v1/community/updates — Update-Check für importierte Profile
GET /api/v1/community/update/{id}/preview — Diff-Vorschau
POST /api/v1/community/update/{id} — Update übernehmen

Discovery + SNMP¶

POST /api/v1/discovery/network-scan
GET /api/v1/discovery/scans/{id}
GET /api/v1/discovery/results
POST /api/v1/discovery/results/{id}/add
POST /api/v1/discovery/results/bulk-add
POST /api/v1/snmp-discovery/walks
GET /api/v1/snmp-discovery/walks/{id}
POST /api/v1/snmp-discovery/walks/{id}/apply

Alert-Rules + Channels¶

GET /api/v1/alert-rules/
POST /api/v1/alert-rules/
POST /api/v1/alert-rules/{id}/test
GET /api/v1/notification-channels/
POST /api/v1/notification-channels/
POST /api/v1/notification-channels/{id}/test

Downtimes + ACK¶

GET /api/v1/downtimes/
POST /api/v1/downtimes/
POST /api/v1/downtimes/bulk — mehrere Checks auf einmal
DELETE /api/v1/downtimes/{id}

Logs¶

POST /api/v1/logs/ingest
GET /api/v1/logs/search
GET /api/v1/logs/stream — SSE
GET /api/v1/logs/sources

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

Dashboards + Reports¶

GET /api/v1/dashboards/
POST /api/v1/dashboards/
GET /api/v1/services/{service_id}/sla
GET /api/v1/tenants/{tenant_id}/sla-report
POST /api/v1/reports/generate

Wiki + AI¶

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
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

Admin¶

POST /api/v1/admin/export
POST /api/v1/admin/import
GET /api/v1/admin/health/snapshot
GET /api/v1/admin/license/status

Audit + Trash¶

GET /api/v1/audit-log/
GET /api/v1/audit-log/export
GET /api/v1/trash/summary
POST /api/v1/trash/{kind}/{id}/restore
DELETE /api/v1/trash/{kind}/{id}/purge

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 · DELETE /api/v1/push/subscriptions/mine/{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 — Zugangsdaten-Sets (Geheimnisse kommen nie zurück)
POST /api/v1/scripts/declaration · POST /api/v1/scripts/resolve · GET /api/v1/scripts/{id}/usage
POST /api/v1/alert-rules/probe-alert — Probealarm durch die echte Kette
Listen unter /alert-rules/ und /notifications/ nehmen q, limit, offset und liefern X-Total-Count

Receiver (Agent / Collector)¶

POST /api/v1/receiver/check-result
POST /api/v1/agent/heartbeat
GET /api/v1/agent/config
GET /api/v1/config/collector/{collector_id}

Antwort-Codes¶

Code	Bedeutung
200 / 201 / 204	Erfolg
400	Validierungsfehler im Request-Body
401	Nicht authentifiziert oder Token abgelaufen
403	Authentifiziert, aber keine Permission
404	Resource nicht gefunden / nicht in deinem Tenant-Scope
409	Konflikt (z. B. Doppelter Hostname)
422	Validierung gescheitert (Pydantic-Detail im Body)
429	Rate-Limit
500	Server-Fehler (sollte nicht passieren — Issue öffnen)
503	Service Unavailable (z. B. Lizenz fehlt für Endpoint)