The Checkmk REST API

One of the advantages of the REST API is that both the software and its documentation come from the same source — the OpenAPI document. Thus the API documentation always matches the software and describes exactly what the API can do. Therefore it is not necessary to describe the reference part of the available resources, methods, parameters etc. in the Checkmk User guide — instead you will find the API documentation separately from this manual, directly in your Checkmk site.

The API with its documentation is versioned and uses a two-level numbering scheme in X.Y format, where X stands for a major version and Y for a minor version. A new minor version only contains backward-compatible changes that have no effect on existing functions. A new major version, on the other hand, contains changes that make the API incompatible with the previous major version (so-called breaking changes). The version numbers of the major and minor versions are part of the URL with which a request is sent to the server. The Checkmk REST API is currently not using the third level (.Z) of the Semantic Versioning standard for a patch version.

Note that the REST API follows a different versioning scheme than that for the Checkmk software. Since a new major version of the API is necessary if there are incompatible API changes, this usually does not match the release cycle of the Checkmk software.

Nevertheless, the correlation between the versions of API documentation and Checkmk software is very straightforward, as you will learn in the next chapter.

The REST API documentation is available in HTML format for viewing in a Web browser.

In the Checkmk GUI, open the API documentation from the navigation bar via Help > Developer resources > REST API documentation. The API documentation is displayed in a new browser window (or browser tab). We will discuss this in more detail in the next chapter.

The API documentation uses a responsive web design consisting of three sections:

The navigation section is scroll-synchronized with the other two sections, which means that if you scroll up or down in the content section, the navigation section automatically scrolls to the appropriate entry in the table of contents.

The responsive web design ensures that the example section does not appear in a very narrow browser window (the examples are then displayed below the corresponding method), and the navigation section is converted into a menu.

In all sections you will find content that you can show and hide, for example, the entries for the endpoints in the navigation section, and nested parameters in the content section. By clicking on > or Expand all you can show the hidden contents, and with ∨ or Collapse all you can hide them again.

In the next chapter you will learn how you can use the API documentation to create concrete requests from the information, send these requests to the Checkmk server, have them executed and monitor that execution and results.

In order to use the REST API in the Checkmk server from a client, the client must prove its identity. The REST API supports the following methods for authentication: Bearer, Web server and Cookie — in this order of precedence. This means, for example, that if authentication with Bearer is successful, none of the other methods will be checked.

The REST API returns the HTTP status code for each request, which you can use to check whether the request was successful. All possible HTTP status codes for the request are listed in the API documentation.

Note that the HTTP status code only provides information about a successful transmission of the request, but not about a successful execution. The commands are executed on the Checkmk server with Livestatus. To be sure that the request via the REST API really does what you intended, you must verify the success yourself. The API documentation, which you can open with Help > Developer resources > REST API interactive GUI, contains an example of a script for this task in the 'Queries through the REST API' section.

To test the REST API, it is advisable to make the requests directly from the Checkmk server, i.e. in this example, the client sending the request and the server receiving it are on the same computer. If you are working as a site user, you can also use local variables such as $OMD_SITE, which refers to the name of the site.

In the following simple examples, we use the sample code contained in the API documentation for the command line program curl, which enables data to be transferred to or from a server without user interaction, for example via HTTP.

The curl command is executed within a bash script. For the preparation, create a script file for each of the requests to be executed in the next section, into which the sample code will later be copied:

The REST API outputs all responses in a single-line JSON format. Since formatted output makes it much easier to read, the following examples show the single-line output formatted in multiple lines. There are various websites and tools for processing the JSON format, for example the command line JSON processor jq.

Before starting, gather some basic information specific to your Checkmk configuration:

These variables are used in the sample code and must be edited by you before sending a request. In the table above you will also find the sample values used in the following.

With a straightforward example we will now demonstrate how to use the REST API. Create a host with its services using a total of four requests. In principle, you proceed in the same way as you would with the Checkmk GUI:

With the REST API GUI you get a new perspective on the API. With this GUI you can interact directly with the API from the browser by sending requests to the server via curl commands, and immediately see the responses. To do this, you have to do without the code examples of the REST API documentation in the API GUI — both views are optimized for their respective functions.

The REST API GUI is generated from the same source as the REST API documentation — the OpenAPI document — and therefore always provides functions that match the API.

You open the API GUI in the Checkmk GUI from the navigation bar, menu Help > Developer resources > REST API interactive GUI. The API GUI is displayed in a new browser window (or browser tab):

In the following we outline how you can execute the first request from the above example (create a host) with the REST API GUI instead of using a script:

The REST API GUI therefore offers you the opportunity to try out the functions of the API quickly and easily, and to familiarize yourself with the functions of the input values as well as with concrete responses.

In contrast to the output from successful commands via script shown so far, the REST API shows you errors in the following way:

Depending on the error, the parameters displayed in the output may vary. However, in status the HTTP status code, and in title they always receive a brief description of the cause of the error.

In most cases, detail will show you detailed information, as the name suggests. In the above example, you can see that there are pending changes in Checkmk, but these were initiated by another user. By default, only changes that have also been made via the API can be activated via the API.

In the next example, the helpful messages are also in the detailed information:

The problem in the above example is that a parameter value does not adhere to the valid value range because the host name contains a slash.

The number of possible errors is of course much greater than the two we have presented here. However, you can see from the examples shown that in its output the REST API usually provides sufficient information on the cause and thus gives you clues for starting the analysis and troubleshooting.

The requests described in this chapter can be found in the API documentation in the Hosts and Folders subfolders. The titles of the respective endpoints contained in the API documentation are the following headings.

Here all folders in the Setup are displayed — recursively starting from the Main folder — without listing the hosts they contain:

Here the hosts in the Main > Linux subfolder are requested:

Here a subfolder Production Hosts is created in Main > Linux — in the file system as the directory production_hosts. The new folder is thereby assigned the Productive system host tag from the predefined host tag group Criticality:

Here, in the Main > Linux > Production Hosts folder, the host mylinuxserver is created with the IP address 192.168.0.123 and the Use piggyback data from other hosts if present host tag:

By displaying a host you receive a list of the attributes assigned to it. This additionally provides the HTTP ETag (entity tag) that you need to be able to modify a host. You can find out more about the ETag in the Show pending changes section.

The ETag is returned in the response header. To display this header, call curl with the -v option (for verbose). Here the host mylinuxserver is queried — and from the response only the line containing the ETag is shown:

Before making the change, get that host’s ETag as described in the preceding section Show a host. You then enter the ETag in the request header under If-Match. Here, the host tag from the Piggyback group that was specified when the host was created is deleted, and the predefined tag API integrations if configured, else Checkmk agent is specified to replace it:

To ensure that a service discovery actually delivers the expected services, on Linux and Windows hosts you must first install and register their respective monitoring agents.

Here, a service discovery is performed on the host mylinuxserver with the refresh option, which corresponds to the Full service scan button in the Checkmk GUI:

Here, two hosts are created in the Main > Linux > Production Hosts folder: the first host with only an IP address, and the second host with a parent host and two labels in addition to its IP address:

Before the complex action of renaming a host can be tackled, it is necessary to activate all changes that have accumulated in its configuration environment. Here the changes for the site mysite are all activated in a single action:

A new name is also going to change the host. Therefore, first get the host’s current ETag, e.g. from mylinuxserver, as described in the Show a host section, and enter this into the request header under If-Match. Here the host is being renamed as mylinuxserver01: