What is Contained in the API

The Nagios XI API is divided into three core sections: Objects, Config, and System. Each section serves a distinct purpose, making the API highly flexible and powerful.

Objects: This section is read-only and provides detailed information about various elements within Nagios XI. It allows users to query important resources, such as hosts, services, and other objects, providing insight into their current states and configurations. The data retrieved from this section can be delivered in either XML or JSON formats, making it easy to integrate and process within other applications or systems.

Config: The Config section is designed for administrative tasks, giving administrators the ability to add, remove, and modify objects such as hosts, services, and other configurations within Nagios XI. This section works directly with the Core Config Manager, allowing the creation and deletion of items. It provides a more dynamic role within the API, as it enables direct management and updates of system configurations to meet specific needs or changes in the infrastructure.

System: Like the Config section, the System section is reserved for administrators and provides the ability to manage the core subsystems of Nagios XI. It allows admins to execute system-level commands, configure system settings, and perform administrative tasks that impact the overall functionality and health of the Nagios XI environment.

Types of API Requests

When interacting with the Nagios XI API, you’ll primarily use four types of HTTP requests to interact with the system: GET, POST, PUT, and DELETE. Each request type serves a different purpose, allowing you to retrieve, create, update, or delete data.

1. GET – Retrieve Data
   The GET request is used to retrieve information from the Nagios XI API. It is typically used to query data such as host status, service status, or configuration details. This is a read-only operation and does not modify any data within the system. For example, you might use a GET request to check the current status of a host or service.
   Example: Retrieve host status or service details.
2. POST – Create or Submit Data
   The POST request is used to send data to the server, typically to create new resources or submit information. For example, when adding a new host or service to Nagios XI, you’ll use a POST request to submit the necessary configuration data. It is used when creating new objects or triggering actions that modify the state of the system.
   Example: Add a new host, service, or update configuration.
3. PUT – Update Data
   The PUT request is used to update or modify an existing resource. It’s typically used when you want to change the configuration of a current host, service, or other object in Nagios XI. Unlike POST, which creates new resources, PUT is meant for updating existing ones.
   Example: Update the configuration of an existing host or service.
4. DELETE – Remove Data
   The DELETE request is used to remove a resource from the Nagios XI system. It’s used when you want to delete objects such as hosts, services, or configurations. Deleting data through the API is a permanent operation, so it’s important to be sure before making this type of request.
   Example: Remove a host or service from the system.

How to Access the API via URL

The Nagios XI API can be accessed in a similar way to how you interact with Nagios XI itself—using a web browser. However, it’s important to note that this method is limited to GET requests, which allow you to retrieve and view data from the system. For tasks like creating, updating, or deleting resources (such as adding hosts or modifying configurations), you’ll need to use a different approach, typically by making POST, PUT, or DELETE requests through code. To get started, simply enter the following URL in your browser:

http://<Your Nagios XI IP>/nagiosxi/api/v1/

At this point, you’ll see an error message—this is expected since no requests have been made yet. To retrieve data, you need to specify the section of the API you want to query and the resource you’re interested in. The URL should look like this:

http://<Your Nagios XI IP>/nagiosxi/api/v1/<section>/<resource>

The section refers to a main area of the API, like objects, config, or system, each offering access to different data or functions. For example, the objects section retrieves information about items like hosts and services, while the config section allows administrators to manage those objects. A resource is a specific data type or object within that section that you query or manipulate. In the objects section, a resource might be hoststatus, showing the current status of hosts, while in the config section, a resource could be service, used to manage service configurations.

To access the API, you’ll also need to include your API key in the URL. This key grants you access to the system and helps determine the permissions you have based on your user role. Depending on your level of access, different sections and resources may be available to you.

To find your API key, navigate to the admin section of Nagios XI. Once you have it, append it to the URL like this:

http://<Your Nagios XI IP>/nagiosxi/api/v1/<section>/<resource>?apikey=<API key>

With everything set up correctly, you should now see real data returned from the API. We’ll use the results from querying hoststatus objects as an example.

By default, the output can appear a bit messy. To improve readability, you can check the Pretty-print checkbox in the UI, which automatically organizes the response. Alternatively, append &pretty=1 to the end of the URL for instant formatting. This makes the output clean, organized, and easy to digest.

http://<Your Nagios XI IP>/nagiosxi/api/v1/objects/hoststatus?apikey=<API key>&pretty=1

Objects are for displaying information, while Config and System are used for adding, removing, or modifying objects. What you write will depend on the action you want to perform with the API. For tasks like editing or modifying data, you’ll need to use code, as this involves making requests that modify the system.

Using with Code

There are many reasons why you might want to access the Nagios XI API programmatically. For instance, you may want to fetch the data posted to the system, monitor host/service statuses, or edit configurations directly through your code. Interacting with the API via code provides flexibility and automation, streamlining your workflow.

To access the API, we can use the appropriate method for interacting with URLs in the programming language you’re working with. Since Nagios XI runs on a web-based interface, the most common language for writing programs inside Nagios XI itself is PHP.

Below is an example of how to access and interact with the Nagios XI API using PHP:

<?php
// Define the server IP and API token
$server_ip = '<Your Nagios XI IP>';  // Replace with your Nagios XI IP
$api_token = '<Your API Key>';  // Replace with your Nagios XI API key

// Build the URL for the API request
$url = "http://$server_ip/nagiosxi/api/v1/<section>/<resource>?apikey=$api_token&pretty=1";

// Initialize cURL session
$ch = curl_init();

// Set the URL for the request
curl_setopt($ch, CURLOPT_URL, $url);

// Set option to return the response as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Execute the request and store the response
$response = curl_exec($ch);

// Check if the request was successful
if ($response === false) {
    echo "Error: " . curl_error($ch);  // Handle errors if the request fails
} else {
    // Decode the JSON response
    $data = json_decode($response, true);
    
    // Output the response (for testing or processing)
    echo "<pre>";
    print_r($data);  // Print the data in a readable format
    echo "</pre>";
}

// Close the cURL session
curl_close($ch);
?>

This code example demonstrates how to send a request to the API, process the response, and display the data in a readable format. It’s a simple and efficient way to automate interactions with Nagios XI.

When interacting with the Nagios XI API to modify data, such as adding a new host, the process differs significantly from simply retrieving information. Instead of making a GET request, we’ll use a POST request, which allows us to send data to the server to create or modify resources. The Config section of the API is used for this purpose, as it enables administrators to make changes to the Nagios XI configuration.

Here’s an example of how you can easily add a host to your Nagios XI setup using the API and PHP. This example walks you through how to structure the API request, send the necessary data, and handle the response. By automating the process like this, you can quickly add hosts to your Nagios XI environment, saving time and reducing the need for manual configuration.

function add_host_via_api($api_token)
{
    // Example: Prepare the POST data
    $data = [
        'host_name'                => 'testapihost',
        'address'                  => '127.0.0.1',
        'check_command'            => 'check_ping!3000,80%!5000,100%',
        'max_check_attempts'       => 2,
        'check_period'             => '24x7',
        'contacts'                 => 'nagiosadmin',
        'notification_interval'    => 5,
        'notification_period'      => '24x7',
        'applyconfig'              => 1
    ];

    // Set up the POST fields
    $post_fields = http_build_query($data);

    // Get the Nagios server IP address
    $server_ip = get_nagios_server_ip();

    // Prepare the URL for the API call
    $url = "http://$server_ip/nagiosxi/api/v1/config/host?apikey=$api_token";

    // Use cURL to send the POST request
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_fields);

    // Execute the cURL request and get the response
    $response = curl_exec($ch);

    // Check for errors in the cURL request
    if ($response === false) {
        return curl_error($ch);
    }

    // Close the cURL handle
    curl_close($ch);

    // Decode the response (optional)
    $response_data = json_decode($response, true);
    
    // Check for success or failure in response
    if (isset($response_data['error'])) {
        return "API Error: " . $response_data['error'];
    }

    return true;  // Return true if the host was added successfully
}

Once the request is made, the response will let you know if the host was added successfully or if there were any issues. We’ve included error handling to catch potential problems, such as network errors or invalid parameters. If everything goes as planned, the function will return true, confirming the host was added with no issues.

This example highlights how modifying your Nagios XI configuration through the API is quite different from just retrieving data. With POST requests, you gain the ability to create, update, and delete resources, giving you full control over your Nagios XI instance.

The other types of calls that can be made are PUT requests which are used to edit existing data in the API and DELETE requests, which deletes aspects of the API. We are going to finish with a look at a DELETE request to the API.

Conclusion

The Nagios XI API is a powerful tool for managing your Nagios XI instance, offering programmatic access to key data and configuration management capabilities. By following the steps outlined here, you can quickly integrate the API into your processes, improving your workflow. Whether you’re querying status data, managing configurations, or integrating with other systems, the Nagios XI API gives you the flexibility to enhance your Nagios XI experience.

For additional assistance, be sure to check the Nagios XI help section for more in-depth resources and support regarding the API.

This guide will walk you through the process of integrating the MultiTech MTR API with Nagios XI, covering configuration, installation, and enabling SMS alerts for users.

Prerequisites

Before proceeding with the integration, ensure you have the following:

• Nagios XI (version 5.5 or newer) installed and running.
• MultiConnect rCell Series Router from MultiTech.
• Administrator access to both Nagios XI and the MultiTech MTR device.
• Network access between the Nagios XI server and the MTR device.

Step 1: Configure MultiTech MTR

Enable HTTPS Access

Nagios XI communicates with the MultiTech MTR device via HTTPS (port 443 by default). Ensure this is enabled in the router settings:

1. Login to the MTR device.
2. Navigate to Administration > Access Configuration > Web Server > HTTPS.
3. Ensure the port is set to 443 (or another preferred port).

Enable SMS Functionality

For SMS alerts to work, ensure that SMS functionality is enabled on the MTR device:

1. Go to SMS > SMS Configuration > SMS Settings.
2. Enable SMS messaging if it is not already active.

Create a Dedicated User for Nagios XI

To avoid authentication conflicts, create an administrator account specifically for Nagios XI:

1. Navigate to Administration > User Accounts.
2. Create a new user account for Nagios XI.

Step 2: Install the MTR Component in Nagios XI

To integrate MultiTech MTR API with Nagios XI, you need to install the Nagios XI MTR Component:

1. Download the MTR component:
   • URL: https://assets.nagios.com/downloads/nagiosxi/components/xi55/mtr.zip
2. Login to Nagios XI as an administrator.
3. Navigate to Admin > System Extensions > Manage Components.
4. Upload the mtr.zip file.

Step 3: Configure the MTR Component in Nagios XI

Once the component is installed, configure it as follows:

1. Navigate to Admin > System Extensions > Manage Components.
2. Locate the MultiTech MTR Component and click the settings icon.
3. On the MultiTech MTR Integration screen, configure the following:
   • Enable Integration: Check this box.
   • IP Address or Hostname: Enter the IP address or domain of the MTR device.
   • HTTPS Port: Ensure this matches the MTR configuration (default 443).
   • Username and Password: Enter the credentials for the dedicated Nagios XI user.
4. Click Apply Settings to save the configuration.

Step 4: Enable SMS Alerts for Users

Each user in Nagios XI who wants to receive SMS notifications must enable them manually:

1. Navigate to User Account Settings.
2. Select Notification Methods and click the MTR tab.
3. Check the SMS Text Message option.
4. Enter the mobile phone number where alerts should be sent.
5. Click Update Settings to enable SMS notifications.

Step 5: Customize SMS Alert Messages

Nagios XI allows users to customize SMS alerts using notification macros:

1. Navigate to User Account Settings.
2. Click on Notification Messages and go to the MTR tab.
3. Customize the format for host and service alerts using macros.
4. Save the changes.

For more details on macros, refer to:
Understanding Nagios XI Notification Variables

Conclusion

Integrating MultiTech MTR API with Nagios XI allows administrators to send SMS alerts directly from Nagios XI, enhancing real-time monitoring and response capabilities. By following the steps outlined above, you can successfully configure and enable this integration.

For additional support, visit:

• Nagios Support Forums: https://support.nagios.com/forum/
• Nagios Knowledgebase: https://support.nagios.com/kb/

Understanding Passive Check Processing

Passive check results can be submitted by external applications and agents to Nagios XI. However, when a passive result is received for a host or service that has not been configured, it is ignored by the monitoring engine. Instead, such hosts and services appear in the Unconfigured Objects interface of Nagios XI, allowing administrators to take action.

Managing Unconfigured Objects in Nagios XI

Navigating to Unconfigured Objects

To review unconfigured objects:

1. Go to Admin > Monitoring Config > Unconfigured Objects.
2. The list will display hosts or services that have received passive results but are not yet monitored.

Adding Unconfigured Objects to Monitoring

To integrate unconfigured objects into Nagios XI monitoring:

Adding a Single Host with Services

• Click the play button next to the unconfigured host to run the Unconfigured Passive Object wizard.

Adding Multiple Hosts with Services

• Select multiple hosts from the list by checking their boxes.
• Click the gear icon at the bottom of the list.
• Follow the wizard steps, configure settings (notifications, groups, parents), and apply the configuration.
• Once applied, these objects will disappear from the Unconfigured Objects section and appear in the monitoring dashboard.

Automating the Configuration of Unconfigured Objects

Nagios XI version 5.5 introduced Auto Configure Settings, which allows automatic creation of monitoring objects from passive check results. To enable this feature:

1. Go to the Auto Configure Settings tab.
2. Check Enable Auto Import to allow Nagios XI to import objects into the Core Config Manager (CCM).
3. (Optional) Enable Apply Configuration to automatically add newly imported objects to Nagios XI’s running configuration.

Customizing Auto Configuration

• Notifications: Define notification settings for new objects.
• Groups: Assign objects to specific host or service groups.
• Advanced Settings: Configure stalking, volatility, and use templates such as xiwizard_passive_host or xiwizard_snmptrap_host for SNMP Traps.

Note: Automatic imports occur every 60 seconds as part of Nagios XI’s background processes.

Removing Unwanted Unconfigured Objects

Unwanted unconfigured objects can be removed using:

• Remove All: Click Clear Unconfigured Objects List to delete all.
• Remove One Host with Services: Click Delete next to the host.
• Remove Multiple Hosts with Services: Select hosts and click the X icon.

Important: Deleted objects will reappear if more passive results are received. To prevent this, stop unwanted passive checks to conserve system resources.

Conclusion

Monitoring unconfigured objects in Nagios XI ensures that all relevant hosts and services are properly integrated into the system. By leveraging the Unconfigured Objects interface, administrators can manually or automatically import necessary hosts and services into monitoring. Proper configuration management helps maintain an efficient and reliable monitoring environment.

For further guidance, visit the Nagios Support Forums or check the Nagios Knowledgebase.

Benefits

1. Automation and Integration

The REST API enables integration between Nagios XI and third-party tools like CMDB systems, ticketing platforms, or configuration management tools. This helps reduce manual work, speed up response times, and ensure tool consistency.

2. Status and System Data Access

The API gives you direct access to monitoring data, host and service statuses, XI server and application data, and performance data returned as JSON. Whether you’re building custom dashboards, feeding data into a business intelligence platform, or simply tracking trends in your own system, the API provides access to up-to-date information.

3. Programmatic Provisioning and Decommissioning

You can create, update, or delete host, service, user, and group configurations and apply configuration via the API. This means you can automate the onboarding of new systems and remove decommissioned ones without ever touching the web interface.

4. Custom Alerting & Response Automation

With current status data at your fingertips, you can customize alerting pipelines — for example, sending alerts to ticketing of chat platforms or triggering automatic remediation workflows in your orchestration tool.

REST API Use Cases and Examples

1. Automated Host and Service Management

When new servers or applications are provisioned, you can use the API to automatically add them to monitoring. This works especially well in dynamic environments such as cloud infrastructure or containerized environments, where systems are constantly spun up and down.

Example Workflow:

• New server instance created in AWS.
• Configuration management (like Ansible) applies baseline configs to the instance.
• Ansible calls the Nagios XI API via a cURL POST command to register the host and services and applies configuration.
• Monitoring and alerting start immediately, without manual intervention.

You can learn more about automation via Ansible using the Nagios XI REST API here:

Nagios XI Ansible Tutorial

Nagios XI supports POST, PUT, and DELETE commands to create, modify, and delete host and service objects, as well as a GET commands, which you can use to review their existing settings. See the Config Reference section of the in-interface guide for examples:

2. Object Control

The API enables you to not just create new objects and modify them but also control the Nagios monitoring engine’s interactions with them. Below are some common examples. Note that you will need to replace things like <XI.Server.IP> and <your-API-key> with your Nagios XI server’s info (conveniently, these two fields are automatically populated correctly in the example commands in the Help >API Docs section of the interface). You’ll also need to replace the data in arguments such as start=1741116177&end=1741123377 with details specific to your request, in this case, with the correct Unix timestamps for the desired time period.

Note that all of the following are single long commands.

• Managing Downtime

To view items in downtime, you can use the GET objects/downtime endpoint:

curl -XGET "http://<XI.Server.IP>/nagiosxi/api/v1/objects/downtime?apikey=<your-API-key>&pretty=1"

curl -XGET "http://<XI.Server.IP>/nagiosxi/api/v1/objects/downtime?apikey=<your-API-key>&pretty=1"

To schedule downtime for a host, you can use the POST system/scheduleddowntime endpoint. :

curl -XPOST "http://<XI.Server.IP>/nagiosxi/api/v1/system/scheduleddowntime?apikey=<your-API-key>&pretty=1" -d "comment=Test downtime creation&start=1741116177&end=1741123377&hosts[]=<hostname1>&hosts[]=<hostname2>"

curl -XPOST "http://<XI.Server.IP>/nagiosxi/api/v1/system/scheduleddowntime?apikey=<your-API-key>&pretty=1" -d "comment=Test downtime creation&start=1741116177&end=1741123377&hosts[]=<hostname1>&hosts[]=<hostname2>"

To take a host out of downtime, you’ll need the internal_downtime_id of the host you wish to remove from downtime, which can be found by running the GET objects/downtime command noted above, then run a command like the following, replacing the number 10 after /scheduleddowntime/10 with the correct ID.

curl -XDELETE "http://<XI.Server.IP>/nagiosxi/api/v1/system/scheduleddowntime/10?apikey=<your-API-key>&pretty=1"

curl -XDELETE "http://<XI.Server.IP>/nagiosxi/api/v1/system/scheduleddowntime/10?apikey=<your-API-key>&pretty=1"

• Make objects Active or Inactive

Inactive objects remain visible in the Nagios XI Core Config Manager but are removed from the Nagios Core monitoring engine configs until reactivated, thus ceasing monitoring. Simply switch the objects back to active and apply the configuration to resume monitoring.

Here, a value of 0 for register=0 makes the service inactive, while a value of 1 makes it active:

curl -XPUT "http://<XI.Server.IP>/nagiosxi/api/v1/config/service/<host name>/<service description>?apikey=<your-API-key>&pretty=1&register=0&applyconfig=1"

curl -XPUT "http://<XI.Server.IP>/nagiosxi/api/v1/config/service/<host name>/<service description>?apikey=<your-API-key>&pretty=1®ister=0&applyconfig=1"

• Schedule a Mass Immediate Check

To schedule an immediate check for hosts, services, or groups, you can use the POST system/massimmediatecheck endpoint:

curl -XPOST "http://<XI.Server.IP>/nagiosxi/api/v1/system/massimmediatecheck?apikey=<your-API-key>&pretty=1" -d "hosts[]=<hostname1>"

curl -XPOST "http://<XI.Server.IP>/nagiosxi/api/v1/system/massimmediatecheck?apikey=<your-API-key>&pretty=1" -d "hosts[]=<hostname1>"

More information can be found in the System Reference section of the in-interface API guide:

Conclusion

The Nagios XI REST API provides comprehensive insight into and control of your monitoring system. Although the GUI-driven options like monitoring wizards, the Core Config Manager, and the many event management tools make the power of Nagios XI accessible to a broad spectrum of users, the API is an invaluable feature for more advanced users and deeper requirements.

You can find more details and API usage examples in the Accessing and Using the XI REST API doc.

This document is intended for use by Nagios Administrators experienced with installing and configuring network devices.

MultiTech MTR API Integration with Nagios XI – 2024 & 2026

MultTech MTR API Integration with XI 2026

MultiTech MTR API Integration with Nagios XI – v5 (Legacy)

MultiTech MTR API Integration with XI 5

Monitoring Unconfigured Objects with Nagios XI – 2024 & 2026

Monitoring Unconfigured Objects with XI 2026

Monitoring Unconfigured Objects with Nagios XI – v5 (Legacy)

Monitoring Unconfigured Objects with XI 5

The ZIP file below contains some sample code for accessing the backend API. You can modify as needed. The access credentials are invisible to the public, and the information to be displayed can be customized (if you don’t mind diving into some PHP).

backendapi-example.zip

Note for Nagios XI 2024 & 2026 Users

Modern versions of Nagios XI now include a REST API, rather than the legacy Backend API.

This document outlines using the REST API to fetch data in JSON format, and to programmatically control your XI system and configurations:

How to Access and Use the Nagios XI REST API

Although Google Map integration is no longer supported, users of modern Nagios XI versions can leverage the World Map component to achieve similar results:

Using the Nagios XI World Map

Nagios XI 2024 & 2026 – REST API

How to Access and Use the Nagios XI REST API

Nagios XI v5 (Legacy) – Backend API

Accessing the Nagios XI 5 Legacy Backend API