Skip to content

Vesana Docs

API cookbook

lukas5001/Vesana

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
HOST=$(curl -s -X POST "$BASE/hosts/" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web03.acme.local",
    "tenant_id": "uuid-of-tenant",
    "profile_id": "uuid-of-linux-profile",
    "ip_address": "10.10.5.13",
    "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={
    "name": "web03.acme.local",
    "tenant_id": tenant_id,
    "profile_id": linux_profile_id,
    "ip_address": "10.10.5.13",
    "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)

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={
            "name":       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",
    "profile_check_id": "profile-check-uuid",
    "display_name": "Disk /var",
    "config_overrides": { "path": "/var" },
    "interval_override": 60
  }'

4. Create custom dashboard programmatically¶

dashboard = requests.post(f"{BASE}/dashboards/", json={
    "name": "Acme NOC",
    "tenant_id": tenant_id,
    "layout": {
        "grid": [
            { "x": 0, "y": 0, "w": 12, "h": 4, "widget": {
                "type": "status_summary",
                "config": { "scope": "tenant" }
            }},
            { "x": 0, "y": 4, "w": 12, "h": 8, "widget": {
                "type": "active_problems",
                "config": { "max_items": 30 }
            }}
        ]
    },
    "variables": [
        { "name": "host", "type": "query", "query": "all_hosts", "multi": True }
    ]
}, headers=HEADERS).json()

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/reports/sla?from=2026-04-01&to=2026-04-30&tenant_id=acme-uuid&format=json" \
  -H "Authorization: Bearer $JWT" \
  | jq '.summary.tenant_availability'

8. Set + cancel maintenance¶

# Schedule
curl -X POST "$BASE/downtimes/" \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "scope": { "tag": "production" },
    "starts_at": "2026-04-30T22:00:00Z",
    "ends_at":   "2026-04-30T23:30:00Z",
    "comment":   "Kernel update"
  }'

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

# With force for higher temperature:
curl -X POST "$BASE/ai/analyze/<service_id>?force=true" \
  -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¶