All examples on this page are based on cURL because most Python programmers can easily transfer that to a requests call. The other way around, it's more complicated.

LAST TESTED ON CHECKMK 2.2.0P1

Table of Contents

Hosts

Showing all Attributes of a Host

Request

Showing the explicit attributes of a host

HOST_NAME="localhost"
PROTOCOL="https"
USERNAME="automation"
SITE_NAME="klapplg"
QUERY_HOST="klappedieerste"
PASSWORD="********"
API_URL="$PROTOCOL://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"

out=$(
  curl \
    -G \
    --request GET \
    --write-out "\nxxx-status_code=%{http_code}\n" \
    --header "Authorization: Bearer $USERNAME $PASSWORD" \
    --header "Accept: application/json" \
    --data-urlencode 'effective_attributes=false' \
    "$API_URL/objects/host_config/$QUERY_HOST")
resp=$( echo "${out}" | grep -v "xxx-status_code" )
code=$( echo "${out}" | awk -F"=" '/^xxx-status_code/ {print $2}')
echo "$resp" | jq
if [[ $code -lt 400 ]]; then     echo "OK"; else     echo "Request error"; fi;

Response

  "domainType": "host_config",
  "id": "klappedieerste",
  "title": "klappedieerste",
  "members": {},
  "extensions": {
    "folder": "",
    "attributes": {
      "ipaddress": "127.0.0.1",
      "snmp_community": {
        "type": "v1_v2_community",
        "community": "publicenemy"
      },
      "labels": {
        "_mpac_spool_new": "/var/spool/mpac/remote/messages/new"
      },
      "meta_data": {
        "created_at": "2021-01-06T07:15:17+00:00",
        "updated_at": "2022-03-31T10:14:32.969304+00:00",
        "created_by": "cmkadmin"
      },
      "tag_criticality": "prod",
      "tag_action_ssh": "action_ssh",
      "tag_agent": "all-agents",
      "tag_snmp_ds": "snmp-v2"
    },
    "effective_attributes": null,
    "is_cluster": false,
    "is_offline": false,
    "cluster_nodes": null
  }

Restrictions

Custom attributes of a host are currently only visible when setting "effective_attributes=true".

Services

Showing a particular service

Request

Showing the Service "Filesystem /boot" for a host

HOST_NAME="localhost"
PROTOCOL="https"
USERNAME="automation"
SITE_NAME="klapplg"
QUERY_HOST="klappedieerste"
PASSWORD="********"
API_URL="$PROTOCOL://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"

out=$(
  curl \
    -G \
    --request GET \
    --write-out "\nxxx-status_code=%{http_code}\n" \
    --header "Authorization: Bearer $USERNAME $PASSWORD" \
    --header "Accept: application/json" \
    --data-urlencode 'service_description=Filesystem /boot' \
    "$API_URL/objects/host/$QUERY_HOST/actions/show_service/invoke")
resp=$( echo "${out}" | grep -v "xxx-status_code" )
code=$( echo "${out}" | awk -F"=" '/^xxx-status_code/ {print $2}')
echo "$resp" | jq
if [[ $code -lt 400 ]]; then     echo "OK"; else     echo "Request error"; fi

Response

  "links": [
    {
      "domainType": "link",
      "rel": "self",
      "href": "http://localhost/klapplg/check_mk/api/1.0/objects/service/klappedieerste-Filesystem%2520%252Fboot",
      "method": "GET",
      "type": "application/json"
    }
  ],
  "domainType": "service",
  "id": "klappedieerste-Filesystem /boot",
  "title": "Service Filesystem /boot",
  "members": {},
  "extensions": {
    "description": "Filesystem /boot",
    "host_name": "klappedieerste",
    "state_type": 1,
    "state": 0,
    "last_check": 1648725749
  }

Acknowledge a Service Problem

Request

Acknowledge a service problem

HOST_NAME="localhost"
PROTOCOL="https"
USERNAME="automation"
SITE_NAME="klapplg"
QUERY_HOST="klappedieerste"
PASSWORD="********"
API_URL="$PROTOCOL://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"

out=$(
  curl  \
	--request POST \
    --write-out "\nxxx-status_code=%{http_code}\n" \
    --header "Authorization: Bearer $USERNAME $PASSWORD" \
    --header "Content-Type: application/json" \
    --header "Accept: */*" \
    --data '{
            "acknowledge_type": "service",
            "sticky": false,
            "persistent": false,
            "notify": false,
            "comment": "This was expected.",
            "host_name": "'$QUERY_HOST'",
            "service_description": "FlavorUsage klapplg"
        }' \
    "$API_URL/domain-types/acknowledge/collections/service")

resp=$( echo "${out}" | grep -v "xxx-status_code" )
code=$( echo "${out}" | awk -F"=" '/^xxx-status_code/ {print $2}')
echo "$resp" | jq
if [[ $code -lt 400 ]]; then     echo "OK"; else     echo "Request error"; fi;

Response

This Request doesn't send a response body, only an HTTP return code.

Queries

The endpoint /domain-types/service/collections/all provides limited access to Livestatus tables. Using queries, you can access tables and filter data.

Query with multiple columns

Request

Query with multiple columns

HOST_NAME="localhost"
PROTOCOL="https"
USERNAME="automation"
SITE_NAME="klapplg"
QUERY_HOST="klappedieerste"
PASSWORD="********"
API_URL="$PROTOCOL://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"

out=$(
  curl \
    -v -G \
    --request GET \
    --write-out "\nxxx-status_code=%{http_code}\n" \
    --header "Authorization: Bearer $USERNAME $PASSWORD" \
    --header "Accept: */*" \
    --data-urlencode 'query={"op": "=", "left": "host_name", "right": "'$QUERY_HOST'"}' \
    --data-urlencode 'columns=host_name' \
    --data-urlencode 'columns=description' \
    "$API_URL/domain-types/service/collections/all"
    )
resp=$( echo "${out}" | grep -v "xxx-status_code" )
code=$( echo "${out}" | awk -F"=" '/^xxx-status_code/ {print $2}')
echo "$resp" | jq
if [[ $code -lt 400 ]]; then     echo "OK"; else     echo "Request error"; fi

Response

    {
      "links": [
        {
          "domainType": "link",
          "rel": "urn:com.checkmk:rels/show",
          "href": "http://localhost/klapplg/check_mk/api/1.0/objects/host/klappedieerste/actions/show_service/invoke?service_description=Temperature+Zone+6",
          "method": "GET",
          "type": "application/json",
          "title": "Show the service Temperature Zone 6"
        }
      ],
      "domainType": "dict",
      "id": "klappedieerste:Temperature Zone 6",
      "title": "Temperature Zone 6 on klappedieerste",
      "members": {},
      "extensions": {
        "host_name": "klappedieerste",
        "description": "Temperature Zone 6"
      }
    }

Complex Queries

Request

Complex Query with AND

HOST_NAME="localhost"
PROTOCOL="https"
USERNAME="automation"
SITE_NAME="klapplg"
QUERY_HOST="klappedieerste"
PASSWORD="********"
API_URL="$PROTOCOL://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"

out=$(
  curl \
    -v -G \
    --request GET \
    --write-out "\nxxx-status_code=%{http_code}\n" \
    --header "Authorization: Bearer $USERNAME $PASSWORD" \
    --header "Accept: */*" \
    --data-urlencode 'query={"op": "and", "expr":[{"op": "=", "left": "host_name", "right": "'$QUERY_HOST'"}, {"op": "=", "left": "description", "right": "CPU utilization"}]}' \
    --data-urlencode 'columns=host_name' \
    --data-urlencode 'columns=description' \
    "$API_URL/domain-types/service/collections/all"
    )
resp=$( echo "${out}" | grep -v "xxx-status_code" )
code=$( echo "${out}" | awk -F"=" '/^xxx-status_code/ {print $2}')
echo "$resp" | jq
if [[ $code -lt 400 ]]; then     echo "OK"; else     echo "Request error"; fi

Response

  "links": [
    {
      "domainType": "link",
      "rel": "self",
      "href": "http://localhost/klapplg/check_mk/api/1.0/domain-types/service/collections/all",
      "method": "GET",
      "type": "application/json"
    }
  ],
  "id": "service",
  "domainType": "service",
  "value": [
    {
      "links": [
        {
          "domainType": "link",
          "rel": "urn:com.checkmk:rels/show",
          "href": "http://localhost/klapplg/check_mk/api/1.0/objects/host/klappedieerste/actions/show_service/invoke?service_description=CPU+utilization",
          "method": "GET",
          "type": "application/json",
          "title": "Show the service CPU utilization"
        }
      ],
      "domainType": "dict",
      "id": "klappedieerste:CPU utilization",
      "title": "CPU utilization on klappedieerste",
      "members": {},
      "extensions": {
        "host_name": "klappedieerste",
        "description": "CPU utilization"
      }
    }
  ],
  "extensions": {}

Request

Complex Query to set a host downtime

HOST_NAME="localhost"
PROTOCOL="https"
USERNAME="automation"
SITE_NAME="klapplg"
QUERY_HOST="klappedieerste"
PASSWORD="********"
API_URL="$PROTOCOL://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"

out=$(
  curl \
    --request POST \
    --write-out "\nxxx-status_code=%{http_code}\n" \
    --header "Authorization: Bearer $USERNAME $PASSWORD" \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '{"comment": "Schedule downtime on host which are in two groups",
             "downtime_type": "host_by_query",
             "duration": 0,
             "end_time": "2022-05-03T13:18:40Z",
             "recur": "fixed",
             "start_time": "2022-05-03T11:48:40Z",
             "query": {"op": "and", "expr":[{"op": ">=", "left": "groups", "right": "hostgroupA"}, {"op": ">=", "left": "groups", "right": "hostgroupB"}]}}' \
    "$API_URL/domain-types/downtime/collections/host")
resp=$( echo "${out}" | grep -v "xxx-status_code" )
code=$( echo "${out}" | awk -F"=" '/^xxx-status_code/ {print $2}')
echo "$resp" | jq
if [[ $code -lt 400 ]]; then     echo "OK"; else     echo "Request error"; fi

Restrictions

It's impossible to restrict the output to a single column; you must request at least two columns.
It's impossible to query data from columns of the type "blob", like "mk_inventory".

Checkmk Knowledge Base

REST-API code examples

Hosts

Showing all Attributes of a Host

Request

Response

Restrictions

Services

Showing a particular service

Request

Response

Acknowledge a Service Problem

Request

Response

Queries

Query with multiple columns

Request

Response

Complex Queries

Request

Response

Request

Restrictions

Related articles