API cookbook

Practical snippets for common tasks.

1. Create host + generate agent token

curlPython

JWT="eyJhbGc..."
BASE="https://your-domain.tld/api/v1"

# Create host ("hostname" is the required field, not "name" —
# the worker correlates check results via (tenant_id, hostname))
HOST=$(curl -s -X POST "$BASE/hosts/" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "web03.acme.local",
    "tenant_id": "uuid-of-tenant",
    "profile_id": "uuid-of-linux-profile",
    "ip_address": "10.10.5.13",
    "monitoring_mode": "agent",
    "tags": ["production", "web"]
  }')

HOST_ID=$(echo "$HOST" | jq -r .id)

# Generate agent token
TOKEN=$(curl -s -X POST "$BASE/hosts/$HOST_ID/agent-token" \
  -H "Authorization: Bearer $JWT" | jq -r .token)

# Install agent
ssh root@web03.acme.local \
  "wget -qO- https://your-domain.tld/agent/install.sh | bash -s -- $TOKEN https://your-domain.tld"

import requests

BASE = "https://your-domain.tld/api/v1"
HEADERS = {"Authorization": f"Bearer {JWT}"}

# Create host
r = requests.post(f"{BASE}/hosts/", json={
    "hostname": "web03.acme.local",
    "tenant_id": tenant_id,
    "profile_id": linux_profile_id,
    "ip_address": "10.10.5.13",
    "monitoring_mode": "agent",
    "tags": ["production", "web"],
}, headers=HEADERS)
host = r.json()

# Agent token
token = requests.post(
    f"{BASE}/hosts/{host['id']}/agent-token",
    headers=HEADERS,
).json()["token"]

print("Token:", token)

The response of POST /hosts/ also contains skipped_checks: checks that the chosen profile_id would have added but couldn't be created because of the mode (e.g. an agent check without monitoring_mode: "agent") — never a silent drop, always visible in the body.

Instead of a local profile_id, the endpoint also accepts community_id (the ID of a profile in the community hub, see Community hub): the server imports it automatically if needed and binds the host to it.

2. Bulk import from CSV

import csv, requests

with open("hosts.csv") as f:
    for row in csv.DictReader(f):
        requests.post(f"{BASE}/hosts/", json={
            "hostname":   row["hostname"],
            "tenant_id":  row["tenant_id"],
            "profile_id": row["profile_id"],
            "ip_address": row["ip"],
        }, headers=HEADERS)

3. Add service to host

curl -X POST "$BASE/host-services/" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "host_id": "host-uuid",
    "tenant_id": "tenant-uuid",
    "profile_check_id": "profile-check-uuid",
    "display_name": "Disk /var",
    "config_overrides": { "path": "/var" },
    "interval_override": 60
  }'

profile_check_id (from a device profile) and check_type (a free check without a profile, an "inline check" with config_overrides carrying the full check config) are mutually exclusive — set exactly one.

4. Create custom dashboard programmatically

dashboard = requests.post(f"{BASE}/dashboards/", json={
    "tenant_id": tenant_id,
    "title": "Acme NOC",
    "config": {
        "schemaVersion": 1,
        "timeSettings": { "from": "now-24h", "to": "now", "refreshInterval": 30 },
        "widgets": {
            "w1": {
                "type": "status_overview",
                "title": "Status overview",
                "dataSource": { "type": "summary", "tenant_ids": [tenant_id] },
                "options": {}
            },
            "w2": {
                "type": "table",
                "title": "Active problems",
                "dataSource": { "type": "status_table", "tenant_ids": [tenant_id] },
                "options": {}
            }
        },
        "layout": {
            "lg": [
                { "i": "w1", "x": 0, "y": 0, "w": 12, "h": 4 },
                { "i": "w2", "x": 0, "y": 4, "w": 12, "h": 8 }
            ]
        }
    }
}, headers=HEADERS).json()

Available widget types (stat, gauge, line_chart, table, status_overview, pie_chart, bar_chart, top_n, heatmap, log_stream, anomaly_list, prediction_list, check_history, status_timeline, text) — see the widget picker when building a dashboard in the web app; the API takes exactly the same config structure the frontend writes.

5. Bulk tag update

hosts = requests.get(f"{BASE}/hosts/?tag=legacy", headers=HEADERS).json()

for h in hosts["items"]:
    new_tags = [t for t in h["tags"] if t != "legacy"] + ["deprecated"]
    requests.patch(f"{BASE}/hosts/{h['id']}", json={"tags": new_tags}, headers=HEADERS)

6. Validate a webhook receiver

import hmac, hashlib, json
from flask import Flask, request

WEBHOOK_SECRET = "<secret from channel config>"

app = Flask(__name__)

@app.route("/vesana-webhook", methods=["POST"])
def receive():
    body = request.get_data()
    sig = request.headers.get("X-Vesana-Signature", "")
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(), body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        return "bad sig", 401

    payload = json.loads(body)
    if payload["status"] == "CRITICAL":
        send_pager(payload["host"]["name"], payload["service"]["display_name"])
    return "ok", 200

7. Pull SLA report

curl "$BASE/tenants/acme-uuid/sla-report?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer $JWT" \
  | jq '.'

8. Set + cancel maintenance

# Schedule maintenance for a host
curl -X POST "$BASE/downtimes/" \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "host_id": "host-uuid",
    "start_at": "2026-04-30T22:00:00Z",
    "end_at":   "2026-04-30T23:30:00Z",
    "comment":  "Kernel update"
  }'

# Recurring instead of one-off: add "recurrence" (an RRULE string), e.g.
# "FREQ=WEEKLY;BYDAY=MO,WE;UNTIL=20260801T220000Z"

# For multiple checks at once: POST $BASE/downtimes/bulk
# with { "service_ids": [...], "start_at": ..., "end_at": ... }

# Cancel early
curl -X DELETE "$BASE/downtimes/<id>" \
  -H "Authorization: Bearer $JWT"

9. Get AI service analysis

curl -X POST "$BASE/ai/analyze/<service_id>" \
  -H "Authorization: Bearer $JWT"

10. Audit export for compliance

curl "$BASE/audit-log/export?from=2026-04-01&format=csv" \
  -H "Authorization: Bearer $JWT" \
  > audit-april.csv

Next

• API reference
• Auth flow