Catch up on the latest product updates, best practices, and expert insights from the Checkmk Conference #12 – Watch the livestream recordings now
back to website

Werk #22022: REST API: Read and write the relations of hosts

Component REST API
Title REST API: Read and write the relations of hosts
Date Oct 12, 2026
Level Trivial Change
Class New Feature
Compatibility Compatible - no manual interaction needed
Checkmk versions & editions
3.0.0b1
Not yet released 		Checkmk Community, Checkmk Pro, Checkmk Ultimate, Checkmk Cloud, Checkmk Ultimate MT

The host endpoints of the REST API now read and write the relations of a host (see werk #20059) in the new host attribute relations. This lets you link a management board and its OS host from a script or an import.

The attribute

relations is a list of links. Sent for the host srv-01-ilo, this makes it the management board of srv-01:

{
  "attributes": {
    "relations": [
      {"kind": "management", "direction": "parent", "host": "srv-01"}
    ]
  }
}
  • kind: the type of the relation. management is the only one for now.
  • direction: the end of the relation this host is at. For management, parent is the management board and child the OS host.
  • host: the related host.

Checkmk writes the other end to the related host for you. Here, srv-01 gets {"kind": "management", "direction": "child", "host": "srv-01-ilo"}. You can set a relation from either of the two hosts.

Keep relations when updating a host

Updating a host with attributes replaces all of its attributes, the relations included. If you leave out relations, the host loses all of its relations, also the ones configured in the host properties, and the related hosts lose their end of them. This applies to the single and the bulk update.

To change other attributes and keep the relations, use update_attributes.

Endpoints

The attribute is shown by:

  • GET /objects/host_config/{host_name}
  • GET /domain-types/host_config/collections/all

and can be set with:

  • POST /domain-types/host_config/collections/all (create a host)
  • POST /domain-types/host_config/collections/clusters (create a cluster)
  • PUT /objects/host_config/{host_name} (update a host)
  • POST /domain-types/host_config/actions/bulk-create/invoke
  • PUT /domain-types/host_config/actions/bulk-update/invoke

Rules

  • relations always holds the complete list of relations of the host, also in update_attributes. To add a relation, send the existing ones plus the new one.
  • "remove_attributes": ["relations"] removes all relations of the host, on both hosts.
  • Writing a relation also changes the related host: you need the permission to edit it as well, it gets a pending change of its own, and its ETag changes.
  • The related host has to exist already. In a bulk create, do not rely on a host created in the same request: create both hosts first and add the relation in a second request.

Errors

  • A link with an unknown kind, or a direction its kind does not have, is refused with status 400. In a bulk request, this refuses the whole request.
  • A relation refused for any other reason, such as a missing related host or a missing permission, skips only that host in a bulk request. The other hosts are saved. The response has status 400 and lists the skipped hosts with the reason under failed_hosts.

Not available elsewhere

Only the host endpoints offer relations. Places that set the same attributes on many hosts, like the "Host attributes to set" of a DCD connection or of an agent registration rule, do not.

To the list of all Werks