Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Integration and Operations

The Zabbix API and Automation

Use the Zabbix JSON-RPC API: request format, API tokens, host.create and problem.get examples, bulk onboarding scripts, error handling, and automation tools.

Clicking through a web interface does not scale to 500 servers. The Zabbix API lets scripts do everything the frontend does: create hosts, link templates, read problems, acknowledge events, export configuration. This lesson explains the JSON-RPC format, authentication, the most used methods, and a safe approach to automation. Zabbix itself cannot run on this site, so requests are shown as read-only examples; the runnable Python code builds, validates and simulates requests without contacting any server.

The protocol

The API is JSON-RPC 2.0 over HTTP POST to https://zabbix.example.com/api_jsonrpc.php. Every request is a JSON object:

JSON
{
  "jsonrpc": "2.0",
  "method": "host.get",
  "params": {
    "output": ["hostid", "host", "name"],
    "selectInterfaces": ["ip", "port"],
    "filter": {"host": ["web01"]}
  },
  "id": 1
}

Required header: Content-Type: application/json-rpc (or application/json in newer versions). The response has either result or error, plus the same id:

JSON
{"jsonrpc": "2.0", "result": [ {"hostid": "10084", "host": "web01"} ], "id": 1}
{"jsonrpc": "2.0", "error": {"code": -32602, "message": "Invalid params.", "data": "..."}, "id": 1}

Note that all IDs are strings.

Authentication

  • Login with user and password using user.login, which returns a session token. From 6.4 or newer the token is passed in an HTTP header Authorization: Bearer <token>; older versions use an auth field in the body.
  • API tokens (Users > API tokens): long-lived tokens for service accounts, with an expiry date. Prefer them for automation; create a dedicated user with only the permissions required.
  • apiinfo.version needs no authentication and is a good connectivity test.

Treat tokens like passwords: environment variables or a secret store, never in Git or in the script text.

The methods you will use

The API is organized by object: host, hostgroup, template, item, trigger, problem, event, user, maintenance, proxy, service, sla, dashboard, configuration and more. Each object has get, create, update, delete, and sometimes special ones (massadd, massupdate, event.acknowledge, configuration.export, configuration.import).

Common parameters in get calls: output (fields or extend or count), select* (include related objects), filter (exact match), search (substring match), sortfield, limit, countOutput. Ask for only the fields you need: output: "extend" over thousands of items is slow.

Creating a host:

JSON
{
  "jsonrpc": "2.0",
  "method": "host.create",
  "params": {
    "host": "web07",
    "interfaces": [{"type": 1, "main": 1, "useip": 1, "ip": "10.0.0.17", "dns": "", "port": "10050"}],
    "groups": [{"groupid": "2"}],
    "templates": [{"templateid": "10001"}],
    "tags": [{"tag": "env", "value": "prod"}],
    "macros": [{"macro": "{$FS.FREE.MIN}", "value": "15"}]
  },
  "id": 2
}

Interface type 1 is Zabbix agent, 2 SNMP, 3 IPMI, 4 JMX. In newer versions host groups are looked up with hostgroup.get first to get their IDs.

Reading current problems with tags and acknowledging one:

JSON
{"jsonrpc":"2.0","method":"problem.get","params":{"output":["eventid","name","severity"],"tags":[{"tag":"service","value":"checkout"}],"recent":true,"sortfield":["eventid"],"sortorder":"DESC","limit":20},"id":3}
{"jsonrpc":"2.0","method":"event.acknowledge","params":{"eventids":"12345","action":6,"message":"Investigating"},"id":4}

The action value is a bit mask: 1 close problem, 2 acknowledge, 4 add message, 8 change severity, 16 unacknowledge, 32 suppress, 64 unsuppress, 128 change to cause, 256 change to symptom. So 6 = acknowledge + message.

Automation patterns

  • Onboarding from a CMDB or cloud inventory: loop through servers, host.get by name, then host.create or host.update. Make the script idempotent: running it twice must not duplicate anything.
  • Maintenance windows from deploy pipelines: create a maintenance via maintenance.create before a release and delete it after.
  • Configuration as code: configuration.export writes templates to YAML or JSON that you store in Git; configuration.import loads them in another environment. Review diffs like source code.
  • Reporting: pull problem.get and history.get into a spreadsheet or data warehouse.
  • Ready-made tools: Ansible collection community.zabbix, Terraform provider for Zabbix, the Python library zabbix_utils (official), and the py-zabbix and pyzabbix libraries.

Stand-in: build and validate requests

This Python runs offline. It builds API requests, checks the ID rules, and parses a canned response including an error, so you can practice the structure.

Python Build and parse JSON-RPC (Python stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: idempotent onboarding

The key rule of an onboarding script is "create only what is missing". This model uses a dictionary as the fake Zabbix.

Python Idempotent host sync (Python stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second run prints an empty list: nothing changes when nothing is wrong.

Good habits

  • Use a dedicated API user with a role limiting API access and host group permissions.
  • Always check for error and log data; retry only on network failures.
  • Batch with massadd or large create arrays carefully; paging with limit avoids timeouts.
  • Test against a staging server. A wrong host.delete filter removes hosts and their history.
  • Note that API behavior changes between major versions; read the manual for your exact release.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which protocol does the Zabbix API use?

    All calls go to api_jsonrpc.php as JSON-RPC 2.0.
  2. 2. Which method needs no authentication?

    apiinfo.version is public, which makes it a convenient reachability check.
  3. 3. What does event.acknowledge with action 6 do?

    6 is 2 (acknowledge) plus 4 (message).
  4. 4. What makes an onboarding script safe to run twice?

    Idempotent scripts compare desired and existing state before acting.

Summary

  • The API is JSON-RPC 2.0; requests carry method, params and id, and responses carry result or error.
  • Use API tokens and dedicated users for automation; never embed secrets in code.
  • Learn get, create, update, delete patterns plus problem.get, event.acknowledge and configuration.export.
  • Make scripts idempotent, ask only for needed fields and test on staging first.

Next: Webhooks and Media Types