Skip to content

API reference

The complete reference is the OpenAPI schema the API generates itself. It lives inside the API container and is not reachable via the domain — how to export it is described in the API overview.

The list below covers the endpoints most commonly needed for automation. All paths start with https://your-domain.tld.

Categorized endpoints

Auth

  • POST /api/v1/auth/login — email + password (optional remember); with 2FA you get a pending_token
  • POST /api/v1/auth/2fa/verify — second factor with pending_token
  • POST /api/v1/auth/2fa/webauthn/begin — passkey challenge for login
  • POST /api/v1/auth/refresh — exchange a valid access token for a new one; ends at the absolute session limit
  • POST /api/v1/auth/logout — ends the web app's cookie session
  • GET /api/v1/auth/me
  • PUT /api/v1/auth/preferences
  • POST /api/v1/auth/change-password — signs out all other sessions and tokens; optional revoke_api_tokens: true also revokes all API/AI access of the account
  • GET /api/v1/auth/step-up/status · POST /api/v1/auth/step-up — confirm identity for sensitive actions
  • 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 sign-in (OIDC, preview feature)

Sensitive actions answer 403 with {"detail": {"code": "STEP_UP_REQUIRED", …}} until the identity has been freshly confirmed (see Auth flow). Objects of other tenants answer 404, never 403.

Collector API keys (POST /api/v1/collectors/{collector_id}/regenerate-key) and agent tokens (POST /api/v1/hosts/{host_id}/agent-token) are separate auth mechanisms for collectors/agents — not user auth, see Auth flow.

Users, roles, teams, tenants

  • GET/POST /api/v1/users/ · PATCH/DELETE /api/v1/users/{user_id}
  • GET/PUT /api/v1/users/{user_id}/access — tenant access and role per 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 and checks

  • GET /api/v1/hosts/ — limit (max. 500), offset, tenant_id, include_inactive; total in X-Total-Count
  • POST /api/v1/hosts/search — filter query (profiles, tenants, status, hostname regex, search text …)
  • POST /api/v1/hosts/
  • GET /api/v1/hosts/{host_id}
  • PATCH /api/v1/hosts/{host_id}
  • DELETE /api/v1/hosts/{host_id} — moves to trash
  • 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 and acknowledge (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/ — list of acknowledgements
  • GET /api/v1/history/{service_id} — history of a check

Profiles

  • 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 — profile as bundle (incl. referenced scripts)
  • POST /api/v1/profiles/import — import bundle
  • POST /api/v1/profiles/{profile_id}/apply
  • GET /api/v1/community/browse — browse the Vesana library
  • GET /api/v1/community/profile/{community_id} — detail
  • POST /api/v1/community/import — install a profile from the library
  • GET /api/v1/community/updates — update check for installed profiles
  • GET /api/v1/community/update/{profile_id}/preview — diff preview
  • POST /api/v1/community/update/{profile_id} — apply update (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 rules + channels

  • 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 — test alert through the real chain
  • GET /api/v1/notifications/ · POST /api/v1/notifications/ — notification channels
  • GET/PATCH/DELETE /api/v1/notifications/{channel_id}
  • POST /api/v1/notifications/{channel_id}/test
  • GET /api/v1/notifications/log — delivery log

The lists under /alert-rules/ and /notifications/ take q, limit, offset and return X-Total-Count.

Maintenance windows

  • GET /api/v1/downtimes/
  • POST /api/v1/downtimes/ — for one host, several hosts (host_ids) or one check (service_id)
  • POST /api/v1/downtimes/bulk — several checks at once
  • 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 rules no longer exist (neither UI nor API) — log alerts run via event log/script checks and regular alert rules.

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}

Reports and SLA (preview feature "Reports (PDF + SLA)")

  • GET /api/v1/sla/services/{service_id}/sla
  • GET /api/v1/sla/tenants/{tenant_id}/sla-report — start, end (ISO timestamps; default: last 30 days)
  • POST /api/v1/reports/generate · POST /api/v1/reports/preview
  • GET/POST /api/v1/reports/schedules

Wiki (preview feature) + 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
  • 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}

In split-container mode the administration endpoints (most of /api/v1/admin/…, plus roles, teams and changes to users) are only reachable via the admin host; on the user host they answer 404 with ADMIN_HOST_REQUIRED.

Audit log + trash

  • GET /api/v1/audit/ — filters 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} — delete permanently

Push (Web Push)

  • GET /api/v1/push/vapid-public-key
  • POST /api/v1/push/subscriptions — create the signed-in user's browser subscription
  • GET /api/v1/push/subscriptions/mine · PATCH/DELETE /api/v1/push/subscriptions/mine/{abo_id}
  • POST /api/v1/push/test

The former native app and its push-tokens endpoints have been removed.

Other

  • GET /api/v1/jump/search?q= — quick search (respects tenant and permissions)
  • GET/POST /api/v1/credential-sets/ · PATCH/DELETE /api/v1/credential-sets/{set_id} — credential sets (secrets are never returned)
  • POST /api/v1/scripts/declaration · POST /api/v1/scripts/resolve · GET /api/v1/scripts/{script_id}/usage

Agent and collector

These paths use the agent token or collector key, not the user token:

  • POST /receiver/api/v1/results — submit check results (X-API-Key or X-Agent-Token)
  • POST /receiver/api/v1/logs/ingest — log ingestion
  • POST /api/v1/agent/heartbeat · GET /api/v1/agent/config
  • GET /api/v1/config/collector/{collector_id}

Response codes

Code Meaning
200 / 201 / 202 / 204 Success
400 Bad request
401 Not authenticated or token expired/revoked
403 Authenticated but no permission — or STEP_UP_REQUIRED
404 Resource not found / not in your tenant scope / preview feature not enabled
409 Conflict (e.g. duplicate hostname)
422 Validation failed (detail in body)
429 Rate limit
500 Server error
503 Service unavailable (e.g. initial setup not completed yet)

Next