Zabbix API with Python: automate hosts and reports

All commands run on zbx01 against its own HTTPS frontend at https://zbx01.lab, using the self-signed certificate from Lesson 3 as the trusted CA. The outputs were captured from a real Zabbix 8.0.0 API and zabbix_utils 2.0.4; IDs and tokens will differ on your system.

1Call the API with curl

Run this on zbx01:

API=https://zbx01.lab/api_jsonrpc.php
CA=/etc/ssl/certs/zbx01.lab.crt
curl -sS --cacert $CA -X POST $API -H 'Content-Type: application/json-rpc' \
  -d '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'; echo
curl -sS --cacert $CA -X POST $API -H 'Content-Type: application/json-rpc' \
  -d '{"jsonrpc":"2.0","method":"host.get","params":{"output":["host"]},"id":1}'; echo

You should see this:

{"jsonrpc":"2.0","result":"8.0.0","id":1}
{"jsonrpc":"2.0","error":{"code":-32602,"message":"Invalid params.","data":"Not authorized."},"id":1}

apiinfo.version is the only method that works without authentication, which makes it a good health check. Everything else answers “Not authorized.” until you send a token.

✅ Checkpoint: apiinfo.version returns “8.0.0” and host.get without a token returns “Not authorized.”

2Log in once with user.login

Run this on zbx01:

curl -sS --cacert $CA -X POST $API -H 'Content-Type: application/json-rpc' \
  -d '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"Zbx@Secure2026"},"id":1}'; echo

You should see this (your session ID will differ):

{"jsonrpc":"2.0","result":"5d84cb5983f57a36866a605fb48a0b6c","id":1}

That 32-character string is a session ID; you could send it as Authorization: Bearer 5d84.... Older guides use "user":"Admin", which 8.0 rejects with Invalid parameter "/": unexpected parameter "user".. Sessions are fine for a quick test, but scripts should not store your Admin password, so next you create a proper API user.

✅ Checkpoint: user.login with username/password returns a session ID.

3Create the “API read-only” role

Go to Users > User roles > Create user role. Name API read-only, User type User. Untick all UI elements and actions (the bot doesn’t use the web pages).

Under Access to API tick Enabled, set API methods to Allow list and add:

Click Add. Don’t add apiinfo.version: it needs no authentication, and 8.0 refuses it in a role list with “Invalid API method “apiinfo.version” for user role”. Then create user group API bots with Frontend access Disabled and Host permissions Lab/Web: Read.

✅ Checkpoint: Users > User roles shows “API read-only” with Access to API Enabled (Allow list, 6 methods), and user group “API bots” has Lab/Web Read.

4Create api-bot and its token

In Users > Users > Create user: Username api-bot, Groups API bots, a long random password (it’s never used to log in), and on the Permissions tab role API read-only. Then go to Users > API tokens > Create API token: Name reporting, User api-bot, tick Set expiration date and time and choose a date 90 days out. Click Add and copy the token from the dialog: it’s shown only once.

Then store it on zbx01:

mkdir -p ~/zbx-api && chmod 700 ~/zbx-api
read -rs -p 'Token: ' T && echo "$T" > ~/zbx-api/ro.token && chmod 600 ~/zbx-api/ro.token; echo
RO=$(cat ~/zbx-api/ro.token)
curl -sS --cacert $CA -X POST $API -H 'Content-Type: application/json-rpc' -H "Authorization: Bearer $RO" \
  -d '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid","host","status"],"selectInterfaces":["ip","port"]},"id":1}'; echo

You should see this (your host ID will differ):

{"jsonrpc":"2.0","result":[{"hostid":"10818","host":"web01","status":"0","interfaces":[{"ip":"192.168.56.81","port":"10050"}]}],"id":1}

Only web01 comes back, because api-bot can read only Lab/Web. The same call with your Admin session would return every host, which is the point of a separate API user.

✅ Checkpoint: host.get with the api-bot token returns web01 and nothing outside Lab/Web.

5Create a write token for automation

The read-only token can’t create anything, so for the next scripts create a second token as Admin: User settings > API tokens > Create API token, name automation, expiry 30 days. Save it as ~/zbx-api/rw.token the same way. At work this token would belong to a dedicated automation user with its own role and host groups, not to a Super admin.

✅ Checkpoint: ~/zbx-api/rw.token exists with mode 600.

6Install zabbix_utils in a virtual environment

Run this on zbx01:

sudo apt install -y python3-venv
python3 -m venv ~/zbx-api/venv
~/zbx-api/venv/bin/pip install zabbix_utils
~/zbx-api/venv/bin/python -c "from zabbix_utils import ZabbixAPI; print('ok')"

The last lines of the pip output are:

Installing collected packages: zabbix_utils
Successfully installed zabbix_utils-2.0.4
ok

Ubuntu 26.04 doesn’t let pip install into the system Python, so a venv is the clean way. The library has no dependencies for the synchronous API.

✅ Checkpoint: Importing ZabbixAPI from the venv prints ok.

7Bulk-create hosts from a CSV

Paste this whole block on zbx01:

cd ~/zbx-api
cat > hosts.csv <<'EOF'
host,ip,group,template
pos-jpr-01,10.20.1.11,Lab/Branch POS,Linux by Zabbix agent active
pos-jpr-02,10.20.1.12,Lab/Branch POS,Linux by Zabbix agent active
pos-pun-01,10.30.1.11,Lab/Branch POS,Linux by Zabbix agnet active
EOF
cat > add_hosts.py <<'EOF'
#!/usr/bin/env python3
"""Create hosts from a CSV file: host,ip,group,template (write token)."""
import csv, os, ssl, sys
from zabbix_utils import ZabbixAPI, APIRequestError

ctx = ssl.create_default_context(cafile="/etc/ssl/certs/zbx01.lab.crt")
api = ZabbixAPI(url="https://zbx01.lab", token=os.environ["ZBX_TOKEN"],
                ssl_context=ctx, skip_version_check=True)

def group_id(name):
    found = api.hostgroup.get(filter={"name": [name]}, output=["groupid"])
    return found[0]["groupid"] if found else api.hostgroup.create(name=name)["groupids"][0]

def template_id(name):
    found = api.template.get(filter={"host": [name]}, output=["templateid"])
    if not found:
        raise ValueError(f'template "{name}" not found')
    return found[0]["templateid"]

with open(sys.argv[1]) as f:
    for row in csv.DictReader(f):
        if api.host.get(filter={"host": [row["host"]]}, output=["hostid"]):
            print(f"skip   {row['host']}: already exists")
            continue
        try:
            r = api.host.create(
                host=row["host"],
                groups=[{"groupid": group_id(row["group"])}],
                templates=[{"templateid": template_id(row["template"])}],
                interfaces=[{"type": 1, "main": 1, "useip": 1, "ip": row["ip"], "dns": "", "port": "10050"}],
                tags=[{"tag": "source", "value": "csv"}])
            print(f"added  {row['host']}: hostid {r['hostids'][0]}")
        except (APIRequestError, ValueError) as e:
            print(f"error  {row['host']}: {e}")
EOF
ZBX_TOKEN=$(cat rw.token) venv/bin/python add_hosts.py hosts.csv

You should see this (your host IDs will differ):

added  pos-jpr-01: hostid 10821
added  pos-jpr-02: hostid 10822
error  pos-pun-01: template "Linux by Zabbix agnet active" not found

The third row has a typo on purpose (“agnet”), and the script reports it instead of crashing halfway through the file. Fix the CSV and run it again: it skips the two existing hosts and adds the third, so the script is safe to re-run. skip_version_check=True is explained in Break It step 3.

Run this on zbx01:

sed -i 's/agnet/agent/' hosts.csv
ZBX_TOKEN=$(cat rw.token) venv/bin/python add_hosts.py hosts.csv

skip   pos-jpr-01: already exists
skip   pos-jpr-02: already exists
added  pos-pun-01: hostid 10823

✅ Checkpoint: Data collection > Hosts shows pos-jpr-01, pos-jpr-02 and pos-pun-01 in Lab/Branch POS with tag source: csv.

8Schedule maintenance from a script

Paste this whole block on zbx01:

cat > maint.py <<'EOF'
#!/usr/bin/env python3
"""Put one host into maintenance for N minutes, starting now (write token)."""
import os, ssl, sys, time
from zabbix_utils import ZabbixAPI

host, minutes = sys.argv[1], int(sys.argv[2])
ctx = ssl.create_default_context(cafile="/etc/ssl/certs/zbx01.lab.crt")
api = ZabbixAPI(url="https://zbx01.lab", token=os.environ["ZBX_TOKEN"],
                ssl_context=ctx, skip_version_check=True)

hostid = api.host.get(filter={"host": [host]}, output=["hostid"])[0]["hostid"]
now = int(time.time())
r = api.maintenance.create(
    name=f"Patching {host} {time.strftime('%Y-%m-%d %H:%M')}",
    active_since=now, active_till=now + minutes * 60,
    hosts=[{"hostid": hostid}],
    timeperiods=[{"timeperiod_type": 0, "start_date": now, "period": minutes * 60}])
print(f"maintenance {r['maintenanceids'][0]} created for {host}, {minutes} min")
EOF
ZBX_TOKEN=$(cat rw.token) venv/bin/python maint.py pos-jpr-01 60

You should see this (your maintenance ID will differ):

maintenance 2 created for pos-jpr-01, 60 min

Within a minute Data collection > Maintenance lists the period as Active and pos-jpr-01 shows the orange maintenance icon. Zabbix rounds the start and end down to the whole minute. This is the script a patching job or a CI pipeline calls before rebooting a server, so nobody gets paged for planned work.

✅ Checkpoint: Data collection > Maintenance shows “Patching pos-jpr-01 …” with state Active.

9Export current problems to CSV with the read-only token

Paste this whole block on zbx01:

cat > report.py <<'EOF'
#!/usr/bin/env python3
"""Export current problems to a CSV file (read-only token)."""
import csv, os, ssl, sys
from datetime import datetime
from zabbix_utils import ZabbixAPI

SEV = ["Not classified", "Information", "Warning", "Average", "High", "Disaster"]
ctx = ssl.create_default_context(cafile="/etc/ssl/certs/zbx01.lab.crt")
api = ZabbixAPI(url="https://zbx01.lab", token=os.environ["ZBX_TOKEN"],
                ssl_context=ctx, skip_version_check=True)
print("Connected to Zabbix API", api.version)

problems = api.problem.get(output=["eventid", "objectid", "name", "severity", "clock", "acknowledged"],
                           sortfield=["eventid"], sortorder="DESC")
triggers = api.trigger.get(triggerids=[p["objectid"] for p in problems],
                           output=["triggerid"], selectHosts=["host"])
host_of = {t["triggerid"]: t["hosts"][0]["host"] for t in triggers}

out = sys.argv[1] if len(sys.argv) > 1 else "problems.csv"
with open(out, "w", newline="") as f:
    w = csv.writer(f)
    w.writerow(["time", "host", "severity", "problem", "acknowledged"])
    for p in problems:
        w.writerow([datetime.fromtimestamp(int(p["clock"])).strftime("%Y-%m-%d %H:%M"),
                    host_of.get(p["objectid"], "?"), SEV[int(p["severity"])],
                    p["name"], "yes" if p["acknowledged"] == "1" else "no"])
print(f"Wrote {len(problems)} problems to {out}")
EOF
ZBX_TOKEN=$(cat ro.token) venv/bin/python report.py && cat problems.csv

You should see this (your problem list will differ):

Connected to Zabbix API 8.0.0
Wrote 3 problems to problems.csv
time,host,severity,problem,acknowledged
2026-11-08 12:30,web01,Warning,Linux: Number of installed packages has been changed,no
2026-11-08 12:00,web01,Information,Linux: /etc/passwd has been changed,no
2026-11-08 11:51,web01,Average,"Linux: FS [/var]: Space is low (used > 80%, total 14.6GB)",no

problem.get gives the trigger ID in objectid but not the host, so the script makes one extra trigger.get call for all of them, instead of one call per problem. Your list will show whatever problems your web01 has; if it’s empty, stop Nginx on web01 for a minute and run it again.

Monitoring > Problems for Lab/Web: the same three problems the script wrote to problems.csv

✅ Checkpoint: problems.csv on zbx01 has a header row and one line per current problem on Lab/Web hosts.