API usage recipes

This page is task-oriented: each recipe is a complete workflow you can adapt, not just an endpoint listing. For the full endpoint catalogue and every field, see the Webserver HTTP API reference. For long-lived credentials, see Create API tokens.

All examples target the Webserver REST API on port 8050 and assume you have a token. The interactive Swagger UI at https://<webserver>:8050/docs/index.html is the quickest way to discover request and response shapes while you build.

Before you start: authentication patterns

There are two ways to authenticate, and the right one depends on how long your automation lives.

For anything unattended, generate an API key once and store it in your secrets manager — do not embed a password in a pipeline.

# One-time: generate a 1-year automation key (returns a token string)
curl -k -X POST https://<webserver>:8050/genAPIKey \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"cicd-pipeline","ttl":"8760","group":"admin"}'

Recipe 1 — A reusable auth helper

Every other recipe builds on this. It fetches a token, fails fast if login is rejected, and exposes a call() helper.

#!/bin/bash
set -euo pipefail

WEBSERVER="https://webserver.example.com:8050"
CACERT="/path/to/webserver.crt"   # or replace --cacert "$CACERT" with -k for testing

# Authenticate once and cache the token for the script's lifetime.
TOKEN=$(curl -s --cacert "$CACERT" -X POST "$WEBSERVER/api/auth" \
  -H "Content-Type: application/json" \
  -d '{"username":"automation","password":"'"$MNS_PASSWORD"'"}' \
  | jq -r '.token')

if [ -z "$TOKEN" ] || [ "$TOKEN" = "null" ]; then
  echo "Authentication failed" >&2
  exit 1
fi

# Thin wrapper: call <METHOD> <PATH> [curl args...]
call() {
  local method="$1"; local path="$2"; shift 2
  curl -s --cacert "$CACERT" -X "$method" "$WEBSERVER$path" \
    -H "Authorization: Bearer $TOKEN" "$@"
}

# Example: list components
call GET /api/components | jq .

Recipe 2 — Bulk-onboard URL monitors from a CSV

You have a list of endpoints to monitor and do not want to click through the UI for each one. Loop over a CSV and POST /api/urls per row.

Given urls.csv:

name,url,probe,sched
Homepage,https://www.example.com,probe-paris,5MIN
Login API,https://api.example.com/health,probe-paris,1MIN
Docs,https://doc.example.com,probe-london,15MIN

# Reuses TOKEN and call() from Recipe 1.
tail -n +2 urls.csv | while IFS=, read -r name url probe sched; do
  echo "Creating monitor: $name"
  call POST /api/urls \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "'"$name"'",
      "url": "'"$url"'",
      "probe": "'"$probe"'",
      "sched": "'"$sched"'",
      "state": "on",
      "tags": "Production,Imported",
      "threshCri": "5000",
      "threshMaj": "3000",
      "threshMin": "1500",
      "emailOnF": "true",
      "emailR": "ops@example.com"
    }' | jq -r '.message // .'
done

The same pattern works for any monitor type — swap /api/urls for /api/tcps, /api/pings, /api/apis, and adjust the body fields. See the reference for each type’s fields.

Recipe 3 — Build a custom status page from the API

Render your own dashboard, Slack digest, or terminal summary by polling the status endpoints. Every monitor type exposes /status (all) and /ko (only the ones that are not OK).

# Print a one-line health summary across every monitor type.
for type in urls apis monitors tcps pings nslookups dbs snmps syss; do
  ko=$(call GET "/api/$type/ko" | jq 'length')
  printf "%-10s %s problem(s)\n" "$type" "${ko:-0}"
done

For an application-level view, query the aggregated Application status instead of individual monitors:

# Aggregated status of every application
call GET /api/apps/status | jq -r '.[] | "\(.name): \(.status)"'

Recipe 4 — Gate a CI/CD deploy on monitor health

Stop a rollout if the target service is already unhealthy, or verify health right after deploying. This snippet exits non-zero when any monitor with a given tag is not OK — drop it into a pipeline stage.

# Fail the pipeline if any "Checkout" URL monitor is not OK.
problems=$(call GET /api/urls/ko \
  | jq '[.[] | select(.tags | test("Checkout"))] | length')

if [ "${problems:-0}" -gt 0 ]; then
  echo "Health gate failed: $problems Checkout monitor(s) not OK" >&2
  call GET /api/urls/ko | jq -r '.[] | select(.tags | test("Checkout")) | "  - \(.display_name): \(.status)"'
  exit 1
fi
echo "Health gate passed"

You can also trigger an on-demand run right after a deploy instead of waiting for the next scheduled check:

# Force an immediate run, then read the fresh result
call GET /api/urls/run/homepage-check
sleep 5
call GET /api/urls/details/homepage-check | jq '{status, responseTime}'

Recipe 5 — Schedule a maintenance window before a release

Suppress alerts automatically during a planned change so the team is not paged for an expected restart. Create a downtime over the affected tags, scoped by a cron schedule and a duration.

# Recurring: every Sunday 02:00, 2-hour window over Production
call POST /downtime/create \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weekly-maintenance",
    "display_name": "Weekly Maintenance Window",
    "tags": "Production",
    "sched": "0 2 * * 0",
    "duration": "120",
    "state": "on"
  }' | jq -r '.message // .'

For a one-off release, create the downtime just before the change and delete it after with DELETE /downtime/delete/:key.

Recipe 6 — Export an inventory of everything you monitor

Produce an audit-friendly snapshot of every monitor and its current status — useful for reviews, capacity planning, or reconciling against a CMDB.

# Combine details from every monitor type into one JSON array
{ for type in urls apis tcps pings nslookups dbs snmps syss; do
    call GET "/api/$type/details" | jq --arg t "$type" '.[]? | {type:$t, name:.display_name, status:.status, probe:.probe, tags:.tags}'
  done
} | jq -s '.' > monitor-inventory.json

echo "Wrote $(jq 'length' monitor-inventory.json) monitors to monitor-inventory.json"

Working with the other components

The Webserver is the control plane, but probes, integrators, and sentinel agents each expose their own API. Reach for them when you need component-local data or actions:

In most automation you only ever talk to the Webserver — it proxies live data from the probes for you on each request.

Error handling and good practices

• Check the code field, not just HTTP status. Responses carry a numeric code (200, 400, 401, 404, 429, 500). A 401 usually means an expired token — re-authenticate. See Status codes.
• Respect the login lockout. Five failed logins from one IP triggers a 5-minute 429 lockout. Cache your token; do not authenticate on every call.
• Refresh before expiry, do not poll-and-retry. User tokens last 15 minutes — call /refresh_token within the window for long-running jobs, or use a long-lived API key.
• Prefer the CA certificate over -k. -k skips TLS verification and is for testing only; use --cacert in anything that runs unattended.
• Use tags to scope automation. Drive bulk operations off tags so a script touches exactly the intended monitors and nothing else.

See also

• Webserver HTTP API — complete endpoint and field reference
• Create API tokens — generate and revoke long-lived keys
• Use cases — the product scenarios these recipes automate
• Embedding dashboards in a portal — publish read-only views without code

Translations

• fr: Recettes d'utilisation de l'API