203 lines
6.9 KiB
Markdown
203 lines
6.9 KiB
Markdown
# Zabbix API Reference
|
|
|
|
**Source:** Zabbix 7.4 official documentation (raw Markdown from git.zabbix.com, fetched 2026-07-07)
|
|
|
|
## Overview
|
|
|
|
- **Protocol:** JSON-RPC 2.0 (not REST). Single endpoint: `POST https://<server>/zabbix/api_jsonrpc.php`
|
|
- All methods are HTTP POST with `Content-Type: application/json-rpc` or `application/json`
|
|
- Request format: `{"jsonrpc":"2.0","method":"<method.name>","params":{...},"id":1}`
|
|
- Response format: `{"jsonrpc":"2.0","result":<data>,"id":1}`
|
|
- Error format: `{"jsonrpc":"2.0","error":{"code":-32602,"message":"...","data":"..."},"id":1}`
|
|
|
|
## Authentication
|
|
|
|
**Recommended: API Token** (Bearer header, no expiration by default)
|
|
|
|
```bash
|
|
curl -H 'Authorization: Bearer <token>' \
|
|
-H 'Content-Type: application/json-rpc' \
|
|
-d '{ "jsonrpc":"2.0","method":"host.get","params":{},"id":1 }' \
|
|
https://example.com/zabbix/api_jsonrpc.php
|
|
```
|
|
|
|
Token management methods: `token.create`, `token.get`, `token.update`, `token.delete`, `token.generate`.
|
|
|
|
## Key Methods for Monitoring Dashboards
|
|
|
|
### host.get — All the hosts
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "host.get",
|
|
"params": {
|
|
"output": ["hostid", "host", "name", "status", "active_available"],
|
|
"selectInterfaces": ["ip", "port"],
|
|
"selectTags": "extend",
|
|
"monitored_hosts": true,
|
|
"limit": 500
|
|
},
|
|
"id": 1
|
|
}
|
|
```
|
|
|
|
Key fields: `hostid`, `host`, `name`, `status` (0=enabled), `active_available` (0=unknown, 1=available, 2=unavailable), `tags`, `interfaces`, `inventory`.
|
|
|
|
Filters: `groupids`, `hostids`, `templateids`, `proxyids`, `tags`, `monitored_hosts`, `with_monitored_items`, `with_triggers`.
|
|
|
|
Sub-selects: `selectInterfaces`, `selectItems`, `selectTriggers`, `selectTags`, `selectParentTemplates`, `selectHostGroups`, `selectInventory`, `selectMacros`.
|
|
|
|
### item.get — Items/metrics with live values
|
|
|
|
Items return `lastvalue`, `prevvalue`, `lastclock` directly — no history query needed for real-time widgets.
|
|
|
|
```json
|
|
{
|
|
"method": "item.get",
|
|
"params": {
|
|
"output": ["itemid", "name", "key_", "lastvalue", "prevvalue", "lastclock", "units", "value_type", "state"],
|
|
"hostids": "<hostid>",
|
|
"monitored": true
|
|
}
|
|
}
|
|
```
|
|
|
|
Filters: `hostids`, `itemids`, `groupids`, `triggerids`, `search` (LIKE on key_), `tags`, `monitored`, `with_triggers`.
|
|
|
|
Filter by item key name: `"search": {"key_": "system.cpu"}` — performs `LIKE "%system.cpu%"`.
|
|
|
|
Value types: `value_type` 0=float, 1=char, 2=log, 3=unsigned int, 4=text, 5=binary.
|
|
|
|
### history.get — Historical values for graphs
|
|
|
|
```json
|
|
{
|
|
"method": "history.get",
|
|
"params": {
|
|
"output": ["clock", "value"],
|
|
"history": 0,
|
|
"itemids": "<itemid>",
|
|
"time_from": 1747000000,
|
|
"time_till": 1747086400,
|
|
"sortfield": "clock",
|
|
"sortorder": "DESC",
|
|
"limit": 500
|
|
}
|
|
}
|
|
```
|
|
|
|
Response: `[{"itemid":"23296","clock":"1351090996","value":"0.085","ns":"563157632"}, ...]`
|
|
|
|
For long-range (>1 month) graphs use `trends.get` (hourly min/max/avg).
|
|
|
|
### problem.get — Active unresolved problems
|
|
|
|
```json
|
|
{
|
|
"method": "problem.get",
|
|
"params": {
|
|
"output": "extend",
|
|
"recent": false,
|
|
"sortfield": ["eventid"],
|
|
"sortorder": "DESC",
|
|
"limit": 100
|
|
}
|
|
}
|
|
```
|
|
|
|
Filters: `hostids`, `groupids`, `severities`, `tags`, `acknowledged`, `suppressed`, `recent` (include recently resolved).
|
|
|
|
### event.get — Full event history
|
|
|
|
More complete than `problem.get`. Returns OK (0) and PROBLEM (1) events. Supports `time_from`/`time_till`, `selectAcknowledges`, `selectAlerts`, `selectTags`, `selectHosts`, `groupBy`, `countOutput`.
|
|
|
|
### event.acknowledge — Acknowledge/modify alerts from portal
|
|
|
|
```json
|
|
{
|
|
"method": "event.acknowledge",
|
|
"params": {
|
|
"eventids": "20427",
|
|
"action": 6,
|
|
"message": "Acknowledged via portal."
|
|
}
|
|
}
|
|
```
|
|
|
|
Bitmask actions: 1=close, 4=add message, 6=acknowledge, 8=change severity, 32=suppress, 64=unsuppress, 128=change to cause, 256=change to symptom.
|
|
|
|
### alert.get — Sent notification history
|
|
|
|
### webhook — Outbound push alerts (30+ pre-built integrations)
|
|
|
|
Built-in media type using custom JavaScript to make HTTP calls. Supports: Slack, Teams, PagerDuty, ServiceNow, Jira, Discord, Telegram, GitHub, and more.
|
|
|
|
## Host CRUD
|
|
|
|
| Method | Permission | Required | Returns |
|
|
|---|---|---|---|
|
|
| `host.create` | Admin/Super admin | `host`, `groups` | `{"hostids":["..."]}` |
|
|
| `host.get` | All users | — | Array of host objects |
|
|
| `host.update` | Admin/Super admin | `hostid` + properties | `{"hostids":["..."]}` |
|
|
| `host.delete` | Admin/Super admin | Host IDs | `{"hostids":["..."]}` |
|
|
| `host.massadd` | Admin/Super admin | `hosts`, objects to add | `{"hostids":["..."]}` |
|
|
| `host.massremove` | Admin/Super admin | `hosts`, objects to remove | `{"hostids":["..."]}` |
|
|
|
|
`host.create` supports: interfaces (SNMPv1/2c/3, agent, IPMI), templates, tags, macros, inventory, proxy assignment.
|
|
|
|
## Item/Trigger/Event CRUD
|
|
|
|
| API | Permissions | Notes |
|
|
|---|---|---|
|
|
| `item.create/update/delete` | Admin/Super admin | Full CRUD |
|
|
| `item.get` | All users | Returns lastvalue |
|
|
| `trigger.create/update/delete` | Admin/Super admin | Expression-based |
|
|
| `trigger.get` | All users | Supports `expandDescription` |
|
|
| `event.acknowledge` | All users | Bitmask-composite action |
|
|
|
|
## Performance Best Practices
|
|
|
|
- **Never use `output: "extend"`** in production — list specific fields
|
|
- **Use `limit` for pagination** — no auto-pagination
|
|
- **Filter aggressively** — `hostids`, `groupids`, tags at the query level
|
|
- **Use `countOutput`** when you just need counts
|
|
- **Use `trends.get`** for >1 month graph data instead of `history.get`
|
|
- **Cache metadata** — items/hosts/triggers change infrequently
|
|
- **`limitSelects`** — limits sub-select record counts
|
|
|
|
## Python Client
|
|
|
|
```python
|
|
from pyzabbix import ZabbixAPI
|
|
|
|
zapi = ZabbixAPI("https://example.com/zabbix")
|
|
zapi.login(api_token="<token>")
|
|
|
|
hosts = zapi.host.get(output=["hostid", "host", "name"], monitored_hosts=True)
|
|
items = zapi.item.get(output=["itemid", "name", "lastvalue"],
|
|
hostids=hosts[0]["hostid"],
|
|
monitored=True)
|
|
history = zapi.history.get(output="extend", history=0,
|
|
itemids=items[0]["itemid"],
|
|
time_from=1747000000,
|
|
time_till=1747086400,
|
|
limit=100)
|
|
```
|
|
|
|
## Additional Resources
|
|
|
|
Complete raw Markdown docs downloaded to `/tmp/zabbix_api/` from this session, covering:
|
|
- `host.md` + host CRUD methods
|
|
- `item.md` + item CRUD methods
|
|
- `trigger.md` + trigger CRUD methods
|
|
- `history.md` + history.get/push
|
|
- `event.md` + event.get/acknowledge
|
|
- `problem.md` + problem.get
|
|
- `alert.md` + alert.get
|
|
- `action.md` + action CRUD
|
|
- `token.md` + token CRUD
|
|
- `webhook.md` — webhook notification configuration
|
|
|
|
Sourced from: Zabbix 7.4 docs at `https://git.zabbix.com/projects/WEB/repos/documentation/raw/en/manual/api/reference/`
|