Table of Contents

Use Zabbix API

Use Zabbix API

zabbix_utils lets you use Zabbix API to manage Zabbix objects, including creating hosts, updating items, retrieving events, and more.

API requests can be made in synchronous or asynchronous mode:

In synchronous mode, your Python script sends a request and waits for a response before continuing, which is suitable for simple, sequential, and predictable operations.
In asynchronous mode, the script sends requests without waiting for each response, allowing other operations to proceed in parallel; this is more efficient for slow requests or large batches of data.

The examples on this page focus on synchronous mode, though asynchronous mode follows similar patterns. Additional examples are available in the zabbix_utils GitHub repository.

Import

To use zabbix_utils for working with Zabbix API, import the ZabbixAPI class in your script:

from zabbix_utils import ZabbixAPI

If you already use a community Python library, you can usually replace that import with ZabbixAPI from zabbix_utils.

Log in

Before making API requests, you must create a ZabbixAPI instance and log in to Zabbix API.

Choose the method that best fits how you manage credentials. You can use your username and password or API tokens.

During initialization

When creating a ZabbixAPI instance, you can provide the Zabbix web interface URL and your credentials all at once:

# Username and password:
       api = ZabbixAPI(url="127.0.0.1/zabbix", user="Admin", password="zabbix")
       
       # API token:
       api = ZabbixAPI(url="127.0.0.1/zabbix", token="your_api_token")

If you prefer to group connection parameters, you can pass them as a Python dictionary and unpack it using Python's keyword argument syntax:

ZABBIX_AUTH = {
           "url": "127.0.0.1/zabbix",
           "user": "Admin",
           "password": "zabbix"
       }
       
       api = ZabbixAPI(**ZABBIX_AUTH)

Using `login()`

You can first create a ZabbixAPI instance with just the Zabbix web interface URL, and later use the login() method with your credentials:

# Username and password:
       api = ZabbixAPI(url="127.0.0.1/zabbix")
       api.login(user="Admin", password="zabbix")
       
       # API token:
       api = ZabbixAPI(url="127.0.0.1/zabbix")
       api.login(token="your_api_token")

Using environment variables

You can first store your credentials as environment variables, for example, by using a terminal:

# Username and password:
       export ZABBIX_USER="Admin"
       export ZABBIX_PASSWORD="zabbix"
       
       # Token:
       export ZABBIX_TOKEN="your_api_token"

Then, if you start your script from the same terminal session, the ZabbixAPI instance in the script requires only the Zabbix web interface URL:

api = ZabbixAPI(url="127.0.0.1/zabbix")

You can also store the URL in an environment variable:

# Username and password:
       export ZABBIX_USER="Admin"
       export ZABBIX_PASSWORD="zabbix"
       export ZABBIX_URL="https://127.0.0.1/zabbix"
       
       # Token:
       export ZABBIX_TOKEN="your_api_token"
       export ZABBIX_URL="https://127.0.0.1/zabbix"

When the URL and credentials are all set as environment variables, the ZabbixAPI instance in the script does not require any arguments at all:

api = ZabbixAPI()

Log out

If you logged in using a username and password, call the logout() method after completing your API operations:

from zabbix_utils import ZabbixAPI
       
       api = ZabbixAPI(url="127.0.0.1/zabbix")
       api.login(user="Admin", password="zabbix")
       
       # API actions go here
       
       api.logout()

Calling the logout() method is not required when using API tokens.

API requests

After you've logged in, you can make any API requests by calling methods described in the Zabbix API method reference.

API methods are called using the following format:

api_instance.zabbix_object.method(parameters)

Some Zabbix API method or object names use words that are reserved keywords in Python (e.g., import). To avoid Python errors, add an underscore to the method or object name when using it in Python (e.g., api.configuration.import_).

For example, to see a list of hosts with host.get:

# 1. Import ZabbixAPI from zabbix_utils:
       from zabbix_utils import ZabbixAPI
       
       # 2. Create the ZabbixAPI instance and log in:
       api = ZabbixAPI(url="127.0.0.1/zabbix")
       api.login(user="Admin", password="zabbix")
       
       # 3. Retrieve hosts matching a filter:
       hosts = api.host.get(
           filter={
               "host": [
                   "Zabbix server",
                   "Linux server"
               ]
           }
       )
       
       # 4. Iterate over returned hosts and print each host's details:
       for host in hosts:
           print(host)
       
       # 5. Log out from the API to close the session:
       api.logout()

Asynchronous mode

Asynchronous mode lets your script send API requests without waiting for each one to finish. This can make your script more efficient when it needs to perform many API requests or when some requests take a long time.

When using asynchronous mode, there are important differences compared to synchronous mode:

Import Python's asyncio module (you must first install the required dependencies).
Import AsyncZabbixAPI instead of ZabbixAPI.
Write your code inside an async function.
Use await when calling API methods, including login() and logout().

When creating an AsyncZabbixAPI instance, you cannot log in during initialization.

For example, to see a list of hosts with host.get in asynchronous mode:

# 1. Import asyncio for asynchronous mode, and AsyncZabbixAPI from zabbix_utils:
       import asyncio
       from zabbix_utils import AsyncZabbixAPI
       
       # 2. Define the main async function where all API operations will run:
       async def main():
       
           # 3. Create an AsyncZabbixAPI instance and log in (must await):
           api = AsyncZabbixAPI(url="127.0.0.1")
           await api.login(user="User", password="zabbix")
       
           # 4. Retrieve hosts matching a filter (must await):
           hosts = await api.host.get(
               filter={
                   "host": [
                       "Zabbix server",
                       "Linux server"
                   ]
               }
           )
       
           # 5. Iterate over returned hosts and print each host's details:
           for host in hosts:
               print(host)
       
           # 6. Log out from the API to close the session (must await):
           await api.logout()
       
       # 7. Run the async main() function using asyncio's event loop:
       asyncio.run(main())

Examples

The following examples show common Zabbix API tasks using the zabbix_utils library.

Additional examples are available in the examples directory of the zabbix_utils GitHub repository.

Documentation