Get started with the RMON API

Use the RMON API to read monitoring configuration and create checks from your own automation. Requests use the HTTPS address of your RMON installation with the prefix /api/v1.0.

Prepare access

1. Use an individual automation account with access to the intended RMON group. Reading and changing resources require the permissions available to that account.
2. Set its Current group in RMON before obtaining a token. This example uses the account's current group and omits group_id.
3. Use the RMON account's login and password for API authentication. The company OIDC sign-in button is a browser flow; an identity-provider token is not an RMON API token. Ask the administrator to provision an appropriate account for automation.
4. Open https://rmon.example.com/api/v1.0/swagger on your own installation for the endpoint reference. The specification is at /api/v1.0/spec.

On endpoints that accept group_id, use only a group the account is permitted to access. Choosing a display category with check_group does not change access permissions. See roles and groups.

Authenticate, list checks and create one check

Send the token as Authorization: Bearer <access_token> on subsequent requests. Keep tokens and passwords out of URLs, saved examples and logs. Send JSON bodies with Content-Type: application/json.

Worked example with Python 3

The following script lists the first page of checks, then asks before creating one enabled HTTP check. It uses Python's standard library, prompts for the password without displaying it and keeps the token in memory. No notification destinations are assigned to the new check.

Before running it, choose an installed, enabled agent in the account's group. Copy the numeric Agent ID from its card and choose a health endpoint you control that returns HTTP 200. Save the script as rmon_api_example.py and run python3 rmon_api_example.py.

import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

base = input("RMON HTTPS address: ").strip().rstrip("/")
address = urllib.parse.urlsplit(base)
if address.scheme != "https" or not address.netloc or address.username or address.query or address.fragment:
    raise SystemExit("Use your RMON HTTPS address without credentials, query or fragment.")
token = None

def request(method, path, payload=None):
    headers = {"Accept": "application/json"}
    if token:
        headers["Authorization"] = "Bearer " + token
    body = None
    if payload is not None:
        body = json.dumps(payload).encode("utf-8")
        headers["Content-Type"] = "application/json"
    req = urllib.request.Request(base + "/api/v1.0" + path,
                                 data=body, headers=headers, method=method)
    try:
        with urllib.request.urlopen(req, timeout=30) as response:
            result = json.load(response)
    except urllib.error.HTTPError as error:
        raise SystemExit(f"HTTP {error.code}: stop and check the request and RMON logs.") from None
    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError):
        raise SystemExit("No usable response. Check RMON before repeating a create request.") from None
    if isinstance(result, dict) and result.get("status") == "failed":
        raise SystemExit("RMON reported a failed operation. Check its logs before retrying.")
    return result

login = input("RMON login: ").strip()
password = getpass.getpass("RMON password: ")
token = request("POST", "/login", {"login": login, "password": password})["access_token"]
del password

page = request("GET", "/rmon/checks?limit=25&offset=1")
for check in page["results"]:
    print(check["multi_check_id"], check["name"])
print("Only the first page is shown; a check may have several locations.")

if input("Create one test check? Type create: ").strip() != "create":
    raise SystemExit("Finished after reading checks.")
agent_id = int(input("Agent ID from the agent card: "))
target = input("Your health endpoint URL (expected HTTP 200): ").strip()
payload = {
    "name": "API quick start",
    "description": "Temporary API verification check",
    "place": "agent",
    "entities": [agent_id],
    "url": target,
    "method": "get",
    "accepted_status_codes": [200],
    "interval": 60,
    "check_timeout": 5,
    "retries": 2,
    "threshold_timeout": 0,
    "ignore_ssl_error": False,
    "enabled": True
}
created = request("POST", "/rmon/check/http", payload)
check_id = created["id"]
print("Created logical check ID:", check_id)
saved = request("GET", f"/rmon/check/http/{check_id}")
print("Read-back succeeded. Open API quick start in RMON to verify fresh results.")

place: "agent" makes entities a list of agent IDs. Use country or region only with the corresponding location IDs. This example sets the interval and timeout in seconds; threshold_timeout is in milliseconds, with 0 disabling the slow-response threshold.

Verify creation and finish the exercise

1. Open Dashboard → API quick start and confirm the target, assigned agent, interval and success condition.
2. Wait for a result newer than the creation time and then a further result at the configured interval. Creation and read-back confirm saved configuration; they do not confirm that the agent can run the check.
3. If you keep the check, give it a useful name and assign tested notification destinations.
4. Otherwise disable or delete the temporary check in RMON. Re-running the create request creates another check; the name is not an identifier for updating an existing one.

Handle errors and retries

Check both the HTTP status and the returned JSON. Some operations report status: "failed" in the response body. For agent installation or reconfiguration, an accepted response with tasks_ids means work is still running: query GET /api/v1.0/rmon/task-status/{task_id} for each returned ID and inspect its final result before proceeding. See agent management for operational verification.