[comment]: # translation:outdated

[comment]: # aside:3

[comment]: # ({new-ebcec779})
# Use Zabbix API

[zabbix\_utils](https://github.com/zabbix/python-zabbix-utils/blob/main/README.md) lets you use [Zabbix API](/manual/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](#asynchronous-mode) follows similar patterns.
Additional examples are available in the [zabbix_utils](https://github.com/zabbix/python-zabbix-utils/tree/main/examples) GitHub repository.

[comment]: # ({/new-ebcec779})

[comment]: # ({new-8304e91c})
#### Import

To use zabbix\_utils for working with Zabbix API, import the `ZabbixAPI` class in your script:

```python
from zabbix_utils import ZabbixAPI
```

::: noteclassic
If you already use a [community Python library](https://www.zabbix.com/integrations/python), you can usually replace that import with `ZabbixAPI` from zabbix\_utils.
:::

[comment]: # ({/new-8304e91c})

[comment]: # ({new-2fe24fc5})
#### 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](/manual/web_interface/frontend_sections/users/api_tokens).

[comment]: # ({/new-2fe24fc5})

[comment]: # ({new-f5ed9f85})
##### During initialization

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

```python
# 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:

```python
ZABBIX_AUTH = {
    "url": "127.0.0.1/zabbix",
    "user": "Admin",
    "password": "zabbix"
}

api = ZabbixAPI(**ZABBIX_AUTH)
```

[comment]: # ({/new-f5ed9f85})

[comment]: # ({new-3bf35a85})
##### 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:

```python
# 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")
```

[comment]: # ({/new-3bf35a85})

[comment]: # ({new-a8fe2b33})
##### Using environment variables

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

```bash
# 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:

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

You can also store the URL in an environment variable:

```bash
# 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:

```python
api = ZabbixAPI()
```

[comment]: # ({/new-a8fe2b33})

[comment]: # ({new-326ac077})
#### Log out

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

```python
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()
```

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

[comment]: # ({/new-326ac077})

[comment]: # ({new-e970d222})
#### API requests

After you've logged in, you can make any API requests by calling methods described in the Zabbix API [method reference](/manual/api/reference).

API methods are called using the following format:

```python
api_instance.zabbix_object.method(parameters)
```

::: noteclassic
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`](/manual/api/reference/host/get):

```python
# 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()
```

[comment]: # ({/new-e970d222})

[comment]: # ({new-0e327592})
##### 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](/devel/python/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()`.

::: noteimportant
When creating an `AsyncZabbixAPI` instance, you cannot log in [during initialization](#during-initialization).
:::

For example, to see a list of hosts with [`host.get`](/manual/api/reference/host/get) in asynchronous mode:

```python
# 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())
```

[comment]: # ({/new-0e327592})

[comment]: # ({new-5dc3bb95})
#### 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](https://github.com/zabbix/python-zabbix-utils) GitHub repository.

[comment]: # ({/new-5dc3bb95})