Overview
This page provides a basic description of the OP5 Monitor API, which is covered in detail in the API reference documentation you can find on your server.
Note: The online documentation does not include the Nachos API endpoints, so they are described in detail in this section.
OP5 Monitor includes a REST API. You can use the API to:
- Retrieve status information.
- Retrieve report data.
- Update the OP5 Monitor configuration.
Authentication modules
When you have more than one OP5 Monitor authentication module, you need to specify which module you are calling. This is done with the dollar character ($).
This standard example calls the default authentication module:
curl -u user:password https://<op5_server_address>/api/filter/query?query=[hosts]
To call the LDAP authentication module, the query is as follows:
curl -u 'user$LDAP:password' https://<op5_server_address>/api/filter/query?query=[hosts]
To call the local authentication module, the query is as follows:
curl -u 'user$Local:password' https://<op5_server_address>/api//filter/query?query=[hosts]
Note that the dollar sign may require single quotes ('$'), depending on the environment.
For more information about authentication modules, see Authentication modules in Manage authentication.
Filter API
You can use the filter API to retrieve information and statuses about hosts, services, traps, logs, and more, using filters. If you are already familiar with the OP5 Monitor list view syntax, you can create filter queries with minimal character replacements: %20 for space, for example.
For more information about filter syntax, see Manage list view filters.
The two types of filter query you can run are described below.
Filter
You use the filter part to retrieve a list of objects returned by a filter.
The following example retrieves a list of hosts that are not in OK state:https://<op5_server_address>/api/filter/query?query=[hosts]%20state!=0&columns=name,state,acknowledged,has_been_checked
Count
You use the count part to return the count of objects in the filter search.
The following example retrieves a count of the objects using the same query as above:https://<op5_server_address>/api/filter/count?query=[hosts]%20state!=0&columns=name,state,acknowledged,has_been_checked
Example filter query
This example query retrieves hosts that are down, not acknowledged, and not in scheduled downtime:
https://demo.op5.com/api/filter/query?query=[hosts]%20state!=0%20&%20acknowledged=0%20&%20scheduled_downtime_depth=0
For more information about the filter API, see: https://<op5_server_address>/api/help/filter
Configuration API
You can use the configuration API to update object configuration. It uses the same configuration database as the OP5 Monitor user interface. Objects changed by the API are also visible within the user interface configuration. You can use the API to integrate OP5 Monitor with other third-party software.
For more information about the configuration API, see: https://<op5_server_address>/api/help/config
Remove a custom variable from an object
To completely remove a custom variable from the database, perform a PATCH API call with the custom variable bearing the value null.
Example request
curl -u 'your_username:your_password' -k https://<op5_server_address>/api/config/host/hostname -X PATCH -H "content-type: application/json" -d '{"_CUSTOMVAR": null}'
After sending the PATCH request, save your changes. You can do this by clicking Save in the Configuration page, or by API call:
curl -u 'your_username:your_password' -k https://<op5_server_address>/api/config/change -X POST
Command API
You can use the command API to submit commands to OP5 Monitor.
For more information about the command API, see: https://<op5_server_address>/api/help/command
Report API
You can use the report API to retrieve report data in either XML or JSON format.
For more information about the report API, see: https://<op5_server_address>/api/help/report
Magellan API
You can use the Magellan API to manage Autodiscovery jobs and executions. For more information about Autodiscovery, see Using Autodiscovery to find hosts on your network in Manage hosts and services.
For a complete reference of the Magellan API endpoints, see https://<op5_server_address>/api/help/magellan
Nachos API
You can use Nachos for export configuration.
How Nachos export works
When you send a request to the Nachos endpoint, it returns a response and the export is executed in the background.
Error responses
Error responses are returned for all requests that do not result in 2xx or 3xx statuses. The error is in JSON format and always contains a name and description of the error.
Error responses follow the general structure shown below.
[
{
"name": "error_name",
"description": "error_description",
}
]
GET latestexport
Retrieves details about the last executed export.
Example request
curl -k -u 'your_username:your_password' https://localhost/api/nachos/v1/latestexport
Example response
200 — OK
{
"id": "123e4567-e89b-12d3-a456-426655440045",
"creation_time": 1982549018,
"status": "running",
"status_details": [
{
"state": "backup",
"progress": 1.0,
"details": ""
},
{
"state": "config_generation",
"progress": 0.0,
"details": "writing hosts.cfg"
},
{
"state":"verification",
"progress":0.0,
"details":""
},
{
"state":"commit",
"progress":0.0,
"details":""
}
],
"user": "your_username",
"export_type": "user_export"
}
GET exports
Retrieves a list of existing exports, ordered by creation time.
Query parameters
| Parameter | Data type | Description |
|---|---|---|
limit
|
integer |
Limits the exports returned to the most recent exports corresponding to the number. Example: |
sort_by
|
string |
Sort property for exports. Possible values: Example: |
order
|
Sort order for exports. Possible values: |
Example response
200 — OK
[
{
"creation_time": "2019-03-26T12:48:07.000000",
"export_type": "full_export",
"id": "37cba483-6f01-4820-b663-6168a44e3771",
"status": "running",
"status_details": [
{
"details": "",
"progress": 1,
"state": "backup"
},
{
"details": "",
"progress": 0,
"state": "config_generation"
},
{
"details": "",
"progress": 0,
"state": "verification"
},
{
"details": "",
"progress": 0,
"state": "commit"
}
],
"user": "your_username"
},
{
"creation_time": "2019-03-26T12:46:59.000000",
"export_type": "full_export",
"id": "1e0a04e7-5ad1-425b-b12b-6082ee07e1c6",
"status": "success",
"status_details": [
{
"details": "",
"progress": 1,
"state": "backup"
},
{
"details": "",
"progress": 1,
"state": "config_generation"
},
{
"details": "",
"progress": 0,
"state": "verification"
},
{
"details": "",
"progress": 1,
"state": "commit"
}
],
"user": "your_username"
}
]
GET exports/<id>
Retrieves an existing export.
Example request
curl -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports/37cba483-6f01-4820-b663-6168a44e3771
Example response
200 — OK
{
"creation_time": "2019-03-26T12:48:07.000000",
"export_type": "full_export",
"id": "37cba483-6f01-4820-b663-6168a44e3771",
"status": "success",
"status_details": [
{
"details": "",
"progress": 1,
"state": "backup"
},
{
"details": "",
"progress": 1,
"state": "config_generation"
},
{
"details": "",
"progress": 0,
"state": "verification"
},
{
"details": "",
"progress": 1,
"state": "commit"
}
],
"user": "your_username"
}
POST exports
Creates a new export based on the supplied JSON data in the request body.
The POST request must supply the header: Content-Type: application/json
Example request
curl -H "Content-Type: application/json" -X POST -d '{"user": "your_username", "export_type": "full_export"|"user_export"}' -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports
Example response
On successful export creation, it returns the created export along with a location header with a URL to the new export resource.
202 - Accepted
{
"export_type": "full_export",
"status_details": [
{
"state": "backup",
"progress": 0,
"details": ""
},
{
"state": "config_generation",
"progress": 0,
"details": ""
},
{
"state": "verification",
"progress": 0,
"details": ""
},
{
"state": "commit",
"progress": 0,
"details": ""
}
],
"id": "6f568330-a79f-4f28-b258-6b1ab0fa745b",
"creation_time": "2019-03-26T12:57:26.131865",
"user": "administrator",
"status": "pending"
}
401 — Unauthorised
curl -H "Content-Type: application/json" -X POST -d '{"user": "not_your_username", "export_type": "full_export"}' -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports
503 — Service unavailable
If the service is busy exporting data, the Retry-After header is set to a number of seconds.