Configuration via 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 three-level numbering scheme in X.Y.Z format, where X stands for a main release, Y for a minor release and Z for a patch. A new minor release contains new, backward-compatible functions. A new main release may contain changes that make the API incompatible with the previous main release (so-called breaking changes). The version numbers of the main and minor releases are part of the URL used to send a request to the server.

Important: Note that the REST API follows a different versioning scheme than that for the Checkmk software. Since a new main release 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 APIs > 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.

Note: You will surely have noticed that there are more entries covering the REST API in the Help menu. With REST API introduction you can open this article. With REST API interactive GUI you can open another view of the REST API. The entry is called GUI since not only are you shown the REST API functions, but because you can also interact with the API directly from the browser — by sending requests to the server for example. We will introduce the REST API GUI as an alternative to execution by script later in the chapter on the REST API GUI.

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

The navigation section is scroll-synchronised 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.

To test the REST API, it is advisable to make the requests directly from the Checkmk server, i.e. in this example client and server 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 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 to which the sample code is later copied:

The REST API outputs all responses in a single-line JSON format. Since formatted output is much easier to read, for formatted output the cURL sample code uses the command line JSON processor jq. You can use the following command to check whether jq is installed:

and — if not — install the software from stedolan.github.io/jq/download/. If you do not want to use jq, you will have to cope with the unformatted output.

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 three 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 optimised 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 exec ute 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 familiarise 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. Modifying an object via REST API is not done using the object’s ID or title. Instead, the generated ETag is used, which is intended to prevent multiple competing requests from overwriting each other’s values for the same object.

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 preceeding 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: