API reference¶

The full API reference is generated from the FastAPI OpenAPI schema.

Live schema¶

On every Vesana instance:

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

Swagger UI is interactive: open endpoints, try requests directly with the logged-in token.

Categorized endpoints¶

Auth¶

POST /api/v1/auth/login — username + password (optional remember); with 2FA a challenge_token follows
POST /api/v1/auth/2fa/verify
POST /api/v1/auth/refresh — rotates the refresh token; the chain ends at the absolute session limit at the latest
POST /api/v1/auth/logout — ends the session server-side
GET /api/v1/auth/me
PUT /api/v1/auth/preferences
GET /api/v1/auth/sso/{provider}/start — SSO login (OIDC)
POST /api/v1/auth/change-password — logs out all other sessions

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

Collector API keys (/collectors/{id}/...) and agent tokens (/hosts/{id}/agent-token) are separate auth mechanisms for collectors/agents — not user API auth, see Auth flow.

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

Profiles¶

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 — profile as a bundle (incl. referenced scripts)
POST /api/v1/profiles/import — import a bundle
POST /api/v1/profiles/{id}/apply
GET /api/v1/community/browse — search the community hub
GET /api/v1/community/profile/{id} — community detail
POST /api/v1/community/import — import from the hub
GET /api/v1/community/updates — update check for imported profiles
GET /api/v1/community/update/{id}/preview — diff preview
POST /api/v1/community/update/{id} — apply the update

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 — multiple checks at once
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 rules no longer exist (neither UI nor API) — log alerts run via event log/script checks and regular alert rules.

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 — create the browser subscription of the logged-in user
GET /api/v1/push/subscriptions/mine · DELETE /api/v1/push/subscriptions/mine/{id}
POST /api/v1/push/test

The former native app and its push-tokens endpoints are gone.

More¶

GET /api/v1/jump/search?q= — quick search (respects tenant and permissions)
GET/POST /api/v1/credential-sets — credential sets (secrets never come back)
POST /api/v1/scripts/declaration · POST /api/v1/scripts/resolve · GET /api/v1/scripts/{id}/usage
POST /api/v1/alert-rules/probe-alert — test alert through the real chain
Lists under /alert-rules/ and /notifications/ accept q, limit, offset and return 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}

Response codes¶

Code	Meaning
200 / 201 / 204	success
400	request body validation error
401	not authenticated or token expired
403	authenticated but no permission
404	resource not found / not in your tenant scope
409	conflict (e.g. duplicate hostname)
422	validation failed (Pydantic detail in body)
429	rate limit
500	server error (shouldn't happen — open issue)
503	Service Unavailable (e.g. license missing for endpoint)