---
layout: docs
title: REST API
breadcrumb: [ "advanced.html", "Advanced" ]
---


== REST API
{% include new_since.ad version="2.24" %}
Thruk offers a rest api to expose various aspects of Thruk itself and
livestatus information.

 * You can find lots of examples on the link:rest_examples.html[REST API examples page].
 * A list of external commands is here: link:rest_commands.html[REST API commands].

The api can be either accessed by http(s) at http://your_webserver/thruk/r/ or
by cli client:

------
  %> thruk r /hostgroups
------

== Versions

Right now, there is only version 1 of the rest api, so you can either use the
generic url http://your_webserver/thruk/r/ or the version specific
http://your_webserver/thruk/r/v1/.


== Authentication

=== Basic Auth

Basic authentication is possible with the rest API but not recommended. Use API
keys instead.  This is a limitation of the apache configuration which cannot
set the remote user if supplied, but pass through the request if not.

------
  %> curl -gk 'https://username:password@localhost/thruk/r/hosts'
------

=== Cookie Auth

Cookies from the cookie authentication are valid as well if you are logged in
already and will return the results with permissions of the current user.

=== API Key

The web rest api accepts the api key as http header. You can create API keys from
the user profile page if `api_keys_enabled` is enabled in your thruk config or with
the rest api itself using the `/thruk/api_keys` endpoint.

------
  %> curl -H 'X-Thruk-Auth-Key: apikey' \
          -gk 'https://localhost/thruk/r/hosts'
------

=== Superuser API Key
A superuser API key (previously named system api key) can be created by admins
and is not bound to a specific user. Instead you can set a username with the
`X-Thruk-Auth-User` HTTP header. This makes superuser api keys very powerful
and they should be handled with the same care as the secret key.
A superuser key can still be restricted to certain roles.

------
  %> curl -H 'X-Thruk-Auth-Key: apikey' \
          -H 'X-Thruk-Auth-User: automation' \
          -d 'comment=test' \
          -gk 'https://localhost/thruk/r/hosts/localhost/cmd/schedule_host_downtime'
------


=== Secret Key

The web rest api accepts the secret key as http header. The secret key
is usually found in `/var/lib/thruk/secret.key` or `var/thruk/secret.key`
when using OMD.

------
  %> curl -H 'X-Thruk-Auth-Key: secretkey' \
          -H 'X-Thruk-Auth-User: thrukadmin' \
          -gk 'https://localhost/thruk/r/hosts'
------


Since the secretkey gives you superadminpower. You can set the context of the
result to any user you like with the `X-Thruk-Auth-User` HTTP header.

=== Command Line

When using the cli clients, use the `-A` option like:

------
  %> thruk -A user r /
------

Having command line access gives you superadminpower as well, so you can set
the user context to any user you need with the `-A` switch.


== Parameters
You can pass parameters mostly along with `POST` and `PATCH` requests. When
using the cli tool, you can utilize the `-d` parameter with key/value pairs or
with json data. Or you can mix those options.

use key/value pairs:

------
  %> thruk r -m PATCH -d max_check_attempts=3 -d first_notification_delay=10 /hosts/localhost/config
------

use json structure:

------
  %> thruk r -m PATCH -d "{'max_check_attempts':3, 'first_notification_delay':10}" /hosts/localhost/config
------

Using curl, you can set parameters like this:

------
  %> curl -d "alias=test" -d "max_check_attempts=3" http://your_webserver/thruk/r/hosts/localhost/config
------

or you can use json data as well:

------
  %> curl --header "Content-Type: application/json" \
          --X PATCH \
          --data '{"max_check_attempts":3, "first_notification=delay":10}' \
          http://your_webserver/thruk/r/hosts/localhost/config
------

== Filtering

All pages offer filtering using query parameters:

------
  %> thruk r '/hosts?name=localhost'
------

Other operators besides equals like regular expressions are possible with the
bracket syntax:

ex.: return all hosts starting with literal `m`:

------
  %> thruk r '/hosts?name[regex]=^m'
------


ex.: list all services which are currently in a downtime:

------
  %> thruk r '/services?scheduled_downtime_depth[gte]=1'
------

Curl requires you to set the `globoff` option:

------
  %> curl -gk 'https://user:pass@localhost/thruk/r/hosts?name[regex]=^t'
------

ex.: numeric filter using the operators `<`, `>`, `>=` or `+++<=+++` will be expanded
like described in link:rest_commands.html#relative-timestamps[relative timestamps].

list session which had been active within the last 10minutes

------
  %> thruk r '/thruk/sessions?columns=username,max(active)&active[gte]=-10m'
------

Possible operators with their alias:

[options="header",halign="center"]
|==========================
|Operator    |Alias    |Description
|+++ =     +++| eq      |Equal match
|+++ !=    +++| ne      |Not equal match
|+++ ~     +++|         |Regular expression match (case-sensitive)
|+++ !~    +++|         |Negated regular expression match (case-sensitive)
|+++ ~~    +++| regex   |Regular expression match (case-insensitive)
|+++ !~    +++| nregex  |Negated regular expression match (case-insensitive)
|+++ >     +++| gt      |Greater than numeric comparisson
|+++ <     +++| lt      |Lower than numeric comparisson
|+++ >=    +++| gte     |Greater or equal numeric comparisson. `contains` in list context
|+++ <=    +++| lte     |Lower or equal numeric comparisson. `contains not` in list context
|+++ !>=   +++| notin   |`contains not` in list context
|==========================

You can use the alias name to workaround urlencoding issues.


== Complex Filtering

Complex filtering logic is possible by using a simple query language which
supports logical operators. The query can be passed urlencoded with the `q`
parameter. An alternative to url encoding is using a special quote syntax by
encapsulating the query in `+***+`. Everything between `+***+` will be
automatically url encoded. (You still need to get quoting right).

------
  %> thruk r '/hosts?q=***name = "test" or name = "other"***'
------

Another example, fetch all hosts from hostgroups linux and windows which are not ok.

------
  %> thruk r '/hosts?q=***(groups >= "linux" or groups >= "windows") and status != 0***'
------

Example using curl:

------
  %> curl -d 'q=***name = "test"***' 'http://.../thruk/r/hosts'
------

If you need `***` in the query itself, any other three characters will do as well:

------
  %> thruk r '/notifications?q=///message = "test" or name = "other"///
------

Lexical filter can use the same time expands as normal filter:

------
  %> thruk r '/services?q=***last_check <= "-7d"***'
------

This will translate to a filter, selecting all services having a `last_check` date
lower than `now - 7 days`. Note the quotes around the value.


== Sorting

All pages can sort list results by using the `sort` parameter. The sort
parameter can be used multiple times or use comma-separated lists. The order is
ascending unless prefixed with an minus.

ex.: sort by name ascending and status descending:

------
  %> thruk r /hosts?sort=name,-state
------

== Limits

All pages offer limits and offset through the `limit` and `offset` parameter.

The offset starts a 0, so offset=1 strips of the first item and starts the result with the second one.
For example show 10 hosts starting with the item 101:

------
  %> thruk r /hosts?limit=10&offset=100
------

== Columns

All pages offer setting columns with the `columns` parameter.

ex.: return name and state for all hosts:

------
  %> thruk r /hosts?columns=name,state
------


Rename columns by appending `:name` like this:
------
  %> thruk r /hosts?columns=name:host_name,state:status
------


=== Performance Data Columns

Thruk will expand performance data into separate columns for host/service queries.

Ex.: a host with the check_icmp check has the performance data put into the coresponding columns, so the following (shorted) json will be returned.

There are 2 columns for each performance value. One with the value itself and one with the unit.

There is also a hash containing the expanded performance values.

Those columns can be used for filtering or to only select specific performance data columns.

------
  %> thruk r /hosts?limit=1

[
   {
...
      "name" : "icmp checked host",
...
      "perf_data" : "rta=0.030ms;3000.000;5000.000;0; pl=0%;80;100;;",
      "perf_data_expanded" : [
         {
            "crit" : "5000.000",
            "max" : "",
            "min" : "0",
            "name" : "rta",
            "orig" : "rta=0.030ms;3000.000;5000.000;0;",
            "parent" : "",
            "unit" : "ms",
            "value" : "0.030",
            "warn" : "3000.000"
         },
         {
            "crit" : "100",
            "max" : "",
            "min" : "",
            "name" : "pl",
            "orig" : "pl=0%;80;100;;",
            "parent" : "",
            "unit" : "%",
            "value" : "0",
            "warn" : "80"
         }
      ],
      "pl" : "0",
      "pl_unit" : "%",
      "rta" : "0.030",
      "rta_unit" : "ms"
...
   }
]
------

[TIP]
.Filter by performance values
=======
Those columns can also be used for filtering. Ex. get all hosts having packing loss greater zero.

`%> thruk r '/hosts?columns=pl,name&pl[gte]=0'`
=======


=== Custom Data Columns

Thruk will expand custom data values into separate columns for host/service queries.

Those columns can be used for filtering or to only select specific custom values.

------
  %> thruk r '/hosts?limit=1&_WORKER=local'
[
   {
...
      "_THRUK_BP_ID" : "666",
      "_THRUK_NODE_ID" : "node1",
      "_WORKER" : "local",
      "custom_variable_names" : [
         "THRUK_BP_ID",
         "THRUK_NODE_ID",
         "WORKER"
      ],
      "custom_variable_values" : [
         "666",
         "node1",
         "local"
      ],
      "custom_variables" : {
         "THRUK_BP_ID" : "666",
         "THRUK_NODE_ID" : "node1",
         "WORKER" : "local"
      },
...
      "name" : "host with custom variables",
...
   }
]
------

== Aggregation Functions

Aggregation functions can be used to get statistical information.

Available aggregaton functions are:

  * `count`: total number of matches
  * `avg`: calculated average for numerical columns
  * `sum`: calculated sum for numerical columns
  * `min`: calculated minimum value for numerical columns
  * `max`: calculated maximum value for numerical columns

ex.: return average latency over all hosts

------
  %> thruk r '/hosts?columns=avg(latency)'
------

The query can include group by columns without aggregations functions,

ex.: list average execution time over all services grouped by state.

------
  %> thruk r '/services?columns=avg(execution_time),state&sort=avg(execution_time)'
------

Rename columns by appending `:name`
------
  %> thruk r '/thruk/sessions?columns=count(*):sessions'
------

Renaming can be combined with grouping columns.

------
  %> thruk r '/services?columns=avg(execution_time):avg_exec_time,host_name'
------

The group by column can be renamed as well:

------
  %> thruk r '/services?columns=avg(execution_time),peer_name:site'
------

Aggregation functions can be used in filter (alias cannot be used in filter):

------
  %> thruk r '/services?columns=avg(execution_time):exec_time&avg(execution_time)[gt]=0'
------

== Backends / Sites

If you have multiple sites connected to Thruk, you may want to talk only to
specific sites. There are multiple methods to set the backends for your
request. You can combine multiple sites with commas.

* Use a path prefix `/sites/<sitename,...>`:
+
------
  %> thruk r /sites/test,prod/hosts
------
+
* Use the `backends` option with the cli client:
+
------
  %> thruk r -b test,prod /hosts
------
+
* Set the `backends` url parameter:
+
------
  %> thruk r /hosts?backends=test,prod
------

[TIP]
.All Sites
=======
Thruk uses all backends unless they are configured as `hidden=yes`. In that case you can force selecting all backends with the `/sites/ALL/` prefix.
=======

[TIP]
.Local Sites
=======
In case you want to send queries only to local backends (those using a unix socket connection) you can use the `/sites/LOCAL/` prefix.
=======


== Error Handling

Failed rest requests return a hash result along with a HTTP error code:

------
  %> thruk r /none
  {
    "code" : 404,
    "message" : "unknown rest path"
    "description" : "optional additional error messages"
  }
------

== Output Formats

=== JSON

JSON is the default output format.

=== CSV

CSV output is available via `/csv/` path prefix. Column names will be automatically
added as first (commented) line. This can be disabled with the `headers=0` parameter.

.Escaping and nested objects
[CAUTION]
Support for nested objects and escaping of semicolons is limited. Nested Objects will fallback to json encoding. If possible, use json format which is faster and more reliable.

------
  %> thruk r /csv/hosts?columns=name,state
------

------
  %> thruk r '/csv/hosts?columns=name,state&headers=0'
------

------
  %> thruk r /hosts?columns=name,state --csv
------

------
  %> curl -g http://localhost/thruk/r/csv/hosts/stats
------

=== XLS

Excel output is available via `/xls/` path prefix.

------
  %> thruk r /xls/hosts?columns=name,state
------

------
  %> thruk r /hosts?columns=name,state --xls
------

=== Table

Human readable table output is available via `/human/` or `/text/` path prefix.

------
  %> thruk r /human/hosts?columns=name,state
------

------
  %> thruk r /hosts?columns=name,state --human
------

------
  %> thruk r /hosts?columns=name,state --text
------

------
  %> thruk r /hosts?columns=name,state -t
------

== HTTP Methods

HTTP Methods are implemented according to link:https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9[RFC2616] which
is in short:

[options="header"]
|===========================================
| GET     | retrieve ressources, ex.: `GET /thruk/reports` to list all reports.
| POST    | update/create ressources or trigger actions, ex.: `POST /thruk/reports` to create a new report.
| PUT     | overwrite existing ressource, ex.: `PUT /thruk/reports/1` to update an entire existing report. Thruk makes no difference between POST and PUT. You can use PUT for all POST urls and vice versa.
| PATCH   | replace parts of existing ressource, ex.: `PATCH /thruk/reports/1` to set specific attributes of an existing report.
| DELETE  | remove existing ressource, ex.: `DELETE /thruk/reports/1` to remove the report entirely.
|===========================================

== Object configuration notes

To create brand new object configurations (e.g hosts), you MUST use POST /config/objects as documented further down.

POST /*/<name>/config is only used for overwriting existing objects.

After object configuration changes, use the following sequence of steps (similar to the GUI object config tool):

1) GET /config/diff

   a) At this point you can revert the changes by using POST /config/revert

2) POST /config/save

3) POST /config/check

4) POST /config/reload

Make sure to check the output of each step

== Endpoints

You can find lots of examples on the link:rest_examples.html[REST API examples page].

The complete list of available external commands can be found on the link:rest_commands.html[REST API commands page].

See examples and detailed description for all other available rest api urls:

=== GET /

lists all available rest urls.
alias for /index

=== GET /alerts

lists alerts based on logfiles.
alias for /logs?type[~]=^(HOST|SERVICE) ALERT

=== GET /checks/stats

lists host / service check statistics.

[options="header"]
|===========================================
|Attribute                         | Description
|hosts_active_15_perc              | percent of active hosts during the last 15 minutes
|hosts_active_15_sum               | amount of active hosts during the last 15 minutes
|hosts_active_1_perc               | same for last minute
|hosts_active_1_sum                | same for last minute
|hosts_active_5_perc               | same for last 5 minutes
|hosts_active_5_sum                | same for last 5 minutes
|hosts_active_60_perc              | same for last 60 minutes
|hosts_active_60_sum               | same for last 60 minutes
|hosts_active_all_perc             | percent of total active hosts
|hosts_active_all_sum              | amount of total active hosts
|hosts_active_state_change_avg     | average percent state change
|hosts_active_state_change_max     | maximum state change over all active hosts
|hosts_active_state_change_min     | minimum state change over all active hosts
|hosts_active_state_change_sum     | sum state change over all hosts
|hosts_active_sum                  | number of active hosts
|hosts_execution_time_avg          | average execution time over all hosts
|hosts_execution_time_max          | maximum execution time over all hosts
|hosts_execution_time_min          | minimum execution time over all hosts
|hosts_execution_time_sum          | sum execution time over all hosts
|hosts_latency_avg                 | host latency average
|hosts_latency_max                 | minimum host latency
|hosts_latency_min                 | minimum host latency
|hosts_latency_sum                 | sum latency over all hosts
|hosts_passive_15_perc             | percent of passive hosts during the last 15 minutes
|hosts_passive_15_sum              | amount of passive hosts during the last 15 minutes
|hosts_passive_1_perc              | same for last minute
|hosts_passive_1_sum               | same for last minute
|hosts_passive_5_perc              | same for last 5 minutes
|hosts_passive_5_sum               | same for last 5 minutes
|hosts_passive_60_perc             | same for last 60 minutes
|hosts_passive_60_sum              | same for last 60 minutes
|hosts_passive_all_perc            | percent of total passive hosts
|hosts_passive_all_sum             | amount of total passive hosts
|hosts_passive_state_change_avg    | average percent state change for passive hosts
|hosts_passive_state_change_max    | maximum state change over all passive hosts
|hosts_passive_state_change_min    | minimum state change over all passive hosts
|hosts_passive_state_change_sum    | sum state change over all passive hosts
|hosts_passive_sum                 | number of passive hosts
|services_active_15_perc           | percent of active services during the last 15 minutes
|services_active_15_sum            | amount of active services during the last 15 minutes
|services_active_1_perc            | same for last minute
|services_active_1_sum             | same for last minute
|services_active_5_perc            | same for last 5 minutes
|services_active_5_sum             | same for last 5 minutes
|services_active_60_perc           | same for last 60 minutes
|services_active_60_sum            | same for last 60 minutes
|services_active_all_perc          | percent of total active services
|services_active_all_sum           | amount of total active services
|services_active_state_change_avg  | average percent state change
|services_active_state_change_max  | maximum state change over all active services
|services_active_state_change_min  | minimum state change over all active services
|services_active_state_change_sum  | sum state change over all services
|services_active_sum               | number of active services
|services_execution_time_avg       | average execution time over all services
|services_execution_time_max       | maximum execution time over all services
|services_execution_time_min       | minimum execution time over all services
|services_execution_time_sum       | sum execution time over all services
|services_latency_avg              | services latency average
|services_latency_max              | minimum services latency
|services_latency_min              | minimum services latency
|services_latency_sum              | sum latency over all services
|services_passive_15_perc          | percent of passive services during the last 15 minutes
|services_passive_15_sum           | amount of passive services during the last 15 minutes
|services_passive_1_perc           | same for last minute
|services_passive_1_sum            | same for last minute
|services_passive_5_perc           | same for last 5 minutes
|services_passive_5_sum            | same for last 5 minutes
|services_passive_60_perc          | same for last 60 minutes
|services_passive_60_sum           | same for last 60 minutes
|services_passive_all_perc         | percent of total passive services
|services_passive_all_sum          | amount of total passive services
|services_passive_state_change_avg | average percent state change for passive services
|services_passive_state_change_max | maximum state change over all passive services
|services_passive_state_change_min | minimum state change over all passive services
|services_passive_state_change_sum | sum state change over all passive services
|services_passive_sum              | number of passive services
|===========================================


=== POST /cmd

Sends any command.

Required arguments:

  * cmd

Optional arguments:

  * host
  * hostgroup
  * service
  * servicegroup
  * contact
  * contactgroup

=== GET /commands

lists livestatus commands.
see https://www.naemon.io/documentation/usersguide/livestatus.html#commands for details.

=== GET /commands/<name>

lists commands for given name.
alias for /commands?name=<name>

=== GET /commands/<name>/config

Returns configuration for given command.
You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#command

=== POST /commands/<name>/config

Replace command configuration completely, use PATCH to only update specific attributes.

=== PATCH /commands/<name>/config

Update command configuration partially.

=== DELETE /commands/<name>/config

Deletes given command from configuration.

=== GET /comments

lists livestatus comments.
see https://www.naemon.io/documentation/usersguide/livestatus.html#comments for details.

=== GET /comments/<id>

lists comments for given id.
alias for /comments?id=<id>

=== POST /config/check

Returns result from config check. This check does require changes to be saved to disk before running the check.

=== GET /config/diff


Optional arguments:

  * ignore_whitespace

Returns differences between filesystem and stashed config changes.

[options="header"]
|===========================================
|Attribute                         | Description
|file                              | file name of changed file
|output                            | diff output
|peer_key                          | backend id when having multiple sites connected
|===========================================


=== POST /config/discard

Reverts stashed configuration changes.
Alias for /config/revert

=== GET /config/files

returns all config files

[options="header"]
|===========================================
|Attribute                         | Description
|content                           | raw file content
|hex                               | hex sum for this file
|mtime                             | unix timestamp of last modification
|path                              | filesystem path
|peer_key                          | backend id when having multiple sites connected
|readonly                          | readonly flag
|===========================================


=== GET /config/fullobjects

Returns list of all objects with templates expanded.
Used templates are saved to the :TEMPLATES attribute

[options="header"]
|===========================================
|Attribute                         | Description
|...                               | object attributes like defined in the source config files
|:FILE                             | filename and line number
|:ID                               | internal uniq id
|:PEER_KEY                         | id of remote site
|:PEER_NAME                        | name of remote site
|:READONLY                         | flag whether file is readonly
|:TEMPLATES                        | list of used template
|:TYPE                             | object type, ex.: host
|===========================================


=== GET /config/objects

Returns list of all objects with their raw config.
Use /config/fullobjects to get the full expanded config.

[options="header"]
|===========================================
|Attribute                         | Description
|...                               | object attributes like defined in the source config files
|:FILE                             | filename and line number
|:ID                               | internal uniq id
|:PEER_KEY                         | id of remote site
|:PEER_NAME                        | name of remote site
|:READONLY                         | flag whether file is readonly
|:TYPE                             | object type, ex.: host
|===========================================


=== POST /config/objects

Create new object. Besides the actual object config, requires
2 special paramters :FILE and :TYPE.

=== PATCH /config/objects

Change attributes for all matching objects.
This is a very powerful url, for example you could change all hosts which
have max_check_attempts=3 to max_check_attempts=5 with this command:

  thruk r -m PATCH -d max_check_attempts=5 '/config/objects?:TYPE=host&max_check_attempts=3'

=== DELETE /config/objects

Delete objects based on filters.
This is a very powerful url, without filter, all objects would be removed.
Ex.: remove all contacts matching a name:

  thruk r -m DELETE '/config/objects?contact_name=test'

=== POST /config/objects/<id>

Replace object configuration completely.

=== PATCH /config/objects/<id>

Update object configuration partially.

=== DELETE /config/objects/<id>

Remove given object from configuration.

=== GET /config/precheck

Returns result from Thruks config precheck. The precheck does not require changes to be saved to disk before running the check.

[options="header"]
|===========================================
|Attribute                         | Description
|errors                            | list of errors encountered
|failed                            | boolean flag wether configuration check has failed or not
|peer_key                          | backend id when having multiple sites connected
|===========================================


=== POST /config/reload

Reloads configuration with the configured reload command.

=== POST /config/revert

Reverts stashed configuration changes.

=== POST /config/save

Saves stashed configuration changes to disk.

=== GET /contactgroups

lists livestatus contactgroups.
see https://www.naemon.io/documentation/usersguide/livestatus.html#contactgroups for details.

=== GET /contactgroups/<name>

lists contactgroups for given name.
alias for /contactgroups?name=<name>

=== POST /contactgroups/<name>/cmd/...

external commands are documented in detail on a separate commands page.
list of supported commands:

 - link:rest_commands.html#post-contactgroupsnamecmddisable_contactgroup_host_notifications[disable_contactgroup_host_notifications]
 - link:rest_commands.html#post-contactgroupsnamecmddisable_contactgroup_svc_notifications[disable_contactgroup_svc_notifications]
 - link:rest_commands.html#post-contactgroupsnamecmdenable_contactgroup_host_notifications[enable_contactgroup_host_notifications]
 - link:rest_commands.html#post-contactgroupsnamecmdenable_contactgroup_svc_notifications[enable_contactgroup_svc_notifications]

=== GET /contactgroups/<name>/config

Returns configuration for given contactgroup.
You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#contactgroup

=== POST /contactgroups/<name>/config

Replace contactgroup configuration completely, use PATCH to only update specific attributes.

=== PATCH /contactgroups/<name>/config

Update contactgroup configuration partially.

=== DELETE /contactgroups/<name>/config

Deletes given contactgroup from configuration.

=== GET /contacts

lists livestatus contacts.
see https://www.naemon.io/documentation/usersguide/livestatus.html#contacts for details.

=== GET /contacts/<name>

lists contacts for given name.
alias for /contacts?name=<name>

=== POST /contacts/<name>/cmd/...

external commands are documented in detail on a separate commands page.
list of supported commands:

 - link:rest_commands.html#post-contactsnamecmdchange_contact_host_notification_timeperiod[change_contact_host_notification_timeperiod]
 - link:rest_commands.html#post-contactsnamecmdchange_contact_svc_notification_timeperiod[change_contact_svc_notification_timeperiod]
 - link:rest_commands.html#post-contactsnamecmdchange_custom_contact_var[change_custom_contact_var]
 - link:rest_commands.html#post-contactsnamecmddisable_contact_host_notifications[disable_contact_host_notifications]
 - link:rest_commands.html#post-contactsnamecmddisable_contact_svc_notifications[disable_contact_svc_notifications]
 - link:rest_commands.html#post-contactsnamecmdenable_contact_host_notifications[enable_contact_host_notifications]
 - link:rest_commands.html#post-contactsnamecmdenable_contact_svc_notifications[enable_contact_svc_notifications]

=== GET /contacts/<name>/config

Returns configuration for given contact.
You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#contact

=== POST /contacts/<name>/config

Replace contact configuration completely, use PATCH to only update specific attributes.

=== PATCH /contacts/<name>/config

Update contact configuration partially.

=== DELETE /contacts/<name>/config

Deletes given contact from configuration.

=== GET /downtimes

lists livestatus downtimes.
see https://www.naemon.io/documentation/usersguide/livestatus.html#downtimes for details.

=== GET /downtimes/<id>

lists downtimes for given id.
alias for /downtimes?id=<id>

=== GET /hostgroups

lists livestatus hostgroups.
see https://www.naemon.io/documentation/usersguide/livestatus.html#hostgroups for details.

=== GET /hostgroups/<name>

lists hostgroups for given name.
alias for /hostgroups?name=<name>

=== POST /hostgroups/<name>/cmd/...

external commands are documented in detail on a separate commands page.
list of supported commands:

 - link:rest_commands.html#post-hostgroupsnamecmddisable_hostgroup_host_checks[disable_hostgroup_host_checks]
 - link:rest_commands.html#post-hostgroupsnamecmddisable_hostgroup_host_notifications[disable_hostgroup_host_notifications]
 - link:rest_commands.html#post-hostgroupsnamecmddisable_hostgroup_passive_host_checks[disable_hostgroup_passive_host_checks]
 - link:rest_commands.html#post-hostgroupsnamecmddisable_hostgroup_passive_svc_checks[disable_hostgroup_passive_svc_checks]
 - link:rest_commands.html#post-hostgroupsnamecmddisable_hostgroup_svc_checks[disable_hostgroup_svc_checks]
 - link:rest_commands.html#post-hostgroupsnamecmddisable_hostgroup_svc_notifications[disable_hostgroup_svc_notifications]
 - link:rest_commands.html#post-hostgroupsnamecmdenable_hostgroup_host_checks[enable_hostgroup_host_checks]
 - link:rest_commands.html#post-hostgroupsnamecmdenable_hostgroup_host_notifications[enable_hostgroup_host_notifications]
 - link:rest_commands.html#post-hostgroupsnamecmdenable_hostgroup_passive_host_checks[enable_hostgroup_passive_host_checks]
 - link:rest_commands.html#post-hostgroupsnamecmdenable_hostgroup_passive_svc_checks[enable_hostgroup_passive_svc_checks]
 - link:rest_commands.html#post-hostgroupsnamecmdenable_hostgroup_svc_checks[enable_hostgroup_svc_checks]
 - link:rest_commands.html#post-hostgroupsnamecmdenable_hostgroup_svc_notifications[enable_hostgroup_svc_notifications]
 - link:rest_commands.html#post-hostgroupsnamecmdschedule_hostgroup_host_downtime[schedule_hostgroup_host_downtime]
 - link:rest_commands.html#post-hostgroupsnamecmdschedule_hostgroup_svc_downtime[schedule_hostgroup_svc_downtime]

=== GET /hostgroups/<name>/config

Returns configuration for given hostgroup.
You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#hostgroup

=== POST /hostgroups/<name>/config

Replace hostgroups configuration completely, use PATCH to only update specific attributes.

=== PATCH /hostgroups/<name>/config

Update hostgroup configuration partially.

=== DELETE /hostgroups/<name>/config

Deletes given hostgroup from configuration.

=== GET /hostgroups/<name>/outages

list of outages for this hostgroup.

Optional arguments:

  * type              - both | hosts | services
  * timeperiod        - last24hours | lastmonth | thismonth | ...
  * start             - unix timestamp
  * end               - unix timestamp
  * withdowntimes     - 0/1 wheter downtimes should count as outages
  * includesoftstates - 0/1 wheter soft states should be used as well

[options="header"]
|===========================================
|Attribute                         | Description
|class                             | host/service status
|duration                          | outage duration in seconds
|end                               | unix timestamp of outage end
|host                              | host name
|in_downtime                       | 0/1 flag wether this outage is in a downtime
|plugin_output                     | last plugin output during outage
|service                           | service description (only for service outages)
|start                             | unix timestamp of outage start
|type                              | log entry type
|===========================================


=== GET /hostgroups/<name>/stats

hash of livestatus hostgroup statistics.
alias for /hosts/stats?groups[gte]=<name>

=== GET /hosts

lists livestatus hosts.
see https://www.naemon.io/documentation/usersguide/livestatus.html#hosts for details.

=== GET /hosts/<name>

lists hosts for given name.
alias for /hosts?name=<name>

=== GET /hosts/<name>/alerts

lists alerts for given host.
alias for /logs?type[~]=^(HOST|SERVICE) ALERT&host_name=<name>

=== POST /hosts/<name>/cmd/...

external commands are documented in detail on a separate commands page.
list of supported commands:

 - link:rest_commands.html#post-hostsnamecmdacknowledge_host_problem[acknowledge_host_problem]
 - link:rest_commands.html#post-hostsnamecmdacknowledge_host_problem_expire[acknowledge_host_problem_expire]
 - link:rest_commands.html#post-hostsnamecmdadd_host_comment[add_host_comment]
 - link:rest_commands.html#post-hostsnamecmdchange_custom_host_var[change_custom_host_var]
 - link:rest_commands.html#post-hostsnamecmdchange_host_check_timeperiod[change_host_check_timeperiod]
 - link:rest_commands.html#post-hostsnamecmdchange_host_modattr[change_host_modattr]
 - link:rest_commands.html#post-hostsnamecmdchange_host_notification_timeperiod[change_host_notification_timeperiod]
 - link:rest_commands.html#post-hostsnamecmdchange_max_host_check_attempts[change_max_host_check_attempts]
 - link:rest_commands.html#post-hostsnamecmdchange_normal_host_check_interval[change_normal_host_check_interval]
 - link:rest_commands.html#post-hostsnamecmdchange_retry_host_check_interval[change_retry_host_check_interval]
 - link:rest_commands.html#post-hostsnamecmddel_active_host_downtimes[del_active_host_downtimes]
 - link:rest_commands.html#post-hostsnamecmddel_all_host_comments[del_all_host_comments]
 - link:rest_commands.html#post-hostsnamecmddel_comment[del_comment]
 - link:rest_commands.html#post-hostsnamecmddel_downtime[del_downtime]
 - link:rest_commands.html#post-hostsnamecmddelay_host_notification[delay_host_notification]
 - link:rest_commands.html#post-hostsnamecmddisable_all_notifications_beyond_host[disable_all_notifications_beyond_host]
 - link:rest_commands.html#post-hostsnamecmddisable_host_and_child_notifications[disable_host_and_child_notifications]
 - link:rest_commands.html#post-hostsnamecmddisable_host_check[disable_host_check]
 - link:rest_commands.html#post-hostsnamecmddisable_host_event_handler[disable_host_event_handler]
 - link:rest_commands.html#post-hostsnamecmddisable_host_flap_detection[disable_host_flap_detection]
 - link:rest_commands.html#post-hostsnamecmddisable_host_notifications[disable_host_notifications]
 - link:rest_commands.html#post-hostsnamecmddisable_host_svc_checks[disable_host_svc_checks]
 - link:rest_commands.html#post-hostsnamecmddisable_host_svc_notifications[disable_host_svc_notifications]
 - link:rest_commands.html#post-hostsnamecmddisable_passive_host_checks[disable_passive_host_checks]
 - link:rest_commands.html#post-hostsnamecmdenable_all_notifications_beyond_host[enable_all_notifications_beyond_host]
 - link:rest_commands.html#post-hostsnamecmdenable_host_and_child_notifications[enable_host_and_child_notifications]
 - link:rest_commands.html#post-hostsnamecmdenable_host_check[enable_host_check]
 - link:rest_commands.html#post-hostsnamecmdenable_host_event_handler[enable_host_event_handler]
 - link:rest_commands.html#post-hostsnamecmdenable_host_flap_detection[enable_host_flap_detection]
 - link:rest_commands.html#post-hostsnamecmdenable_host_notifications[enable_host_notifications]
 - link:rest_commands.html#post-hostsnamecmdenable_host_svc_checks[enable_host_svc_checks]
 - link:rest_commands.html#post-hostsnamecmdenable_host_svc_notifications[enable_host_svc_notifications]
 - link:rest_commands.html#post-hostsnamecmdenable_passive_host_checks[enable_passive_host_checks]
 - link:rest_commands.html#post-hostsnamecmdprocess_host_check_result[process_host_check_result]
 - link:rest_commands.html#post-hostsnamecmdremove_host_acknowledgement[remove_host_acknowledgement]
 - link:rest_commands.html#post-hostsnamecmdschedule_and_propagate_host_downtime[schedule_and_propagate_host_downtime]
 - link:rest_commands.html#post-hostsnamecmdschedule_and_propagate_triggered_host_downtime[schedule_and_propagate_triggered_host_downtime]
 - link:rest_commands.html#post-hostsnamecmdschedule_forced_host_check[schedule_forced_host_check]
 - link:rest_commands.html#post-hostsnamecmdschedule_forced_host_svc_checks[schedule_forced_host_svc_checks]
 - link:rest_commands.html#post-hostsnamecmdschedule_host_check[schedule_host_check]
 - link:rest_commands.html#post-hostsnamecmdschedule_host_downtime[schedule_host_downtime]
 - link:rest_commands.html#post-hostsnamecmdschedule_host_svc_checks[schedule_host_svc_checks]
 - link:rest_commands.html#post-hostsnamecmdschedule_host_svc_downtime[schedule_host_svc_downtime]
 - link:rest_commands.html#post-hostsnamecmdsend_custom_host_notification[send_custom_host_notification]
 - link:rest_commands.html#post-hostsnamecmdset_host_notification_number[set_host_notification_number]
 - link:rest_commands.html#post-hostsnamecmdstart_obsessing_over_host[start_obsessing_over_host]
 - link:rest_commands.html#post-hostsnamecmdstop_obsessing_over_host[stop_obsessing_over_host]

=== GET /hosts/<name>/commandline

displays commandline for check command of given hosts.

[options="header"]
|===========================================
|Attribute                         | Description
|check_command                     | name of the check_command including arguments
|command_line                      | full expanded command line (if possible)
|error                             | contains the error if expanding failed for some reason
|host_name                         | host name
|peer_key                          | backend id when having multiple sites connected
|===========================================


=== GET /hosts/<name>/config

Returns configuration for given host.
You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#host

=== POST /hosts/<name>/config

Replace host configuration completely, use PATCH to only update specific attributes.

=== PATCH /hosts/<name>/config

Update host configuration partially.

=== DELETE /hosts/<name>/config

Deletes given host from configuration.

=== GET /hosts/<name>/notifications

lists notifications for given host.
alias for /logs?class=3&host_name=<name>

=== GET /hosts/<name>/outages

list of outages for this host.

Optional arguments:

  * type              - both | hosts | services
  * timeperiod        - last24hours | lastmonth | thismonth | ...
  * start             - unix timestamp
  * end               - unix timestamp
  * withdowntimes     - 0/1 wheter downtimes should count as outages
  * includesoftstates - 0/1 wheter soft states should be used as well

[options="header"]
|===========================================
|Attribute                         | Description
|class                             | host/service status
|duration                          | outage duration in seconds
|end                               | unix timestamp of outage end
|host                              | host name
|in_downtime                       | 0/1 flag wether this outage is in a downtime
|plugin_output                     | last plugin output during outage
|start                             | unix timestamp of outage start
|type                              | log entry type
|===========================================


=== GET /hosts/<name>/services

lists services for given host.
alias for /services?host_name=<name>

=== GET /hosts/outages

list of outages for all hosts.

Optional arguments:

  * type              - both | hosts | services
  * timeperiod        - last24hours | lastmonth | thismonth | ...
  * start             - unix timestamp
  * end               - unix timestamp
  * withdowntimes     - 0/1 wheter downtimes should count as outages
  * includesoftstates - 0/1 wheter soft states should be used as well

[options="header"]
|===========================================
|Attribute                         | Description
|class                             | host/service status
|duration                          | outage duration in seconds
|end                               | unix timestamp of outage end
|host                              | host name
|in_downtime                       | 0/1 flag wether this outage is in a downtime
|plugin_output                     | last plugin output during outage
|start                             | unix timestamp of outage start
|type                              | log entry type
|===========================================


=== GET /hosts/stats

hash of livestatus host statistics.

[options="header"]
|===========================================
|Attribute                         | Description
|active_checks_disabled_active     | number of active hosts which have active checks disabled
|active_checks_disabled_passive    | number of passive hosts which have active checks disabled
|down                              | number of down hosts
|down_and_ack                      | number of down hosts which are acknowledged
|down_and_disabled_active          | number of active down hosts which have active checks disabled
|down_and_disabled_passive         | number of passive down hosts which have active checks disabled
|down_and_scheduled                | number of down hosts which are in a scheduled downtime
|down_and_unhandled                | number of unhandled down hosts
|eventhandler_disabled             | number of hosts with eventhandlers disabled
|flapping                          | number of flapping hosts
|flapping_disabled                 | number of hosts with flapping detection disabled
|notifications_disabled            | number of hosts with notifications disabled
|outages                           | number of network outages
|passive_checks_disabled           | number of hosts which do not accept passive check results
|pending                           | number of pending hosts
|pending_and_disabled              | number of pending hosts with active checks disabled
|pending_and_scheduled             | number of pending hosts which are in a scheduled downtime
|plain_down                        | number of down hosts which are not acknowleded or in a downtime
|plain_pending                     | number of pending hosts which are not acknowleded or in a downtime
|plain_unreachable                 | number of unreachable hosts which are not acknowleded or in a downtime
|plain_up                          | number of up hosts which are not acknowleded or in a downtime
|total                             | total number of hosts
|total_active                      | total number of active hosts
|total_passive                     | total number of passive hosts
|unreachable                       | number of unreachable hosts
|unreachable_and_ack               | number of unreachable hosts which are acknowledged
|unreachable_and_disabled_active   | number of active unreachable hosts which have active checks disabled
|unreachable_and_disabled_passive  | number of passive unreachable hosts which have active checks disabled
|unreachable_and_scheduled         | number of unreachable hosts which are in a scheduled downtime
|unreachable_and_unhandled         | number of unhandled unreachable hosts
|up                                | number of up hosts
|up_and_disabled_active            | number of active up hosts which have active checks disabled
|up_and_disabled_passive           | number of passive up hosts which have active checks disabled
|up_and_scheduled                  | number of up hosts which are in a scheduled downtime
|===========================================


=== GET /hosts/totals

hash of livestatus host totals statistics.
its basically a reduced set of /hosts/stats.

[options="header"]
|===========================================
|Attribute                         | Description
|down                              | number of down hosts
|down_and_unhandled                | number of down hosts which are neither acknowledged nor in scheduled downtime
|pending                           | number of pending hosts
|total                             | total number of hosts
|unreachable                       | number of unreachable hosts
|unreachable_and_unhandled         | number of unreachable hosts which are neither acknowledged nor in scheduled downtime
|up                                | number of up hosts
|===========================================


=== GET /index

lists all available rest urls.

[options="header"]
|===========================================
|Attribute                         | Description
|description                       | description of the url
|protocol                          | protocol to use for this url
|url                               | the rest url
|===========================================


=== GET /lmd/sites

lists connected sites. Only available if LMD (`use_lmd`) is enabled.

[options="header"]
|===========================================
|Attribute                         | Description
|addr                              | address of the remote site
|bytes_received                    | total bytes received from this site
|bytes_send                        | total bytes send to this site
|federation_addr                   | contains the real address if using federation
|federation_key                    | contains the real peer key if using federation
|federation_name                   | contains the real name if using federation
|federation_type                   | contains the real backend type if using federation
|idling                            | flag if the connection is in idle mode
|key                               | primary id of this site
|last_error                        | last error message
|last_online                       | timestamp when the site was last time online
|last_query                        | timestamp of the last received query for this site
|last_update                       | timestamp of the last update
|lmd_last_cache_update             | same as last_update
|name                              | name of the site
|parent                            | parent id for lmd federation setups
|peer_key                          | same as `key`
|peer_name                         | same as `name`
|queries                           | number of queries received
|response_time                     | response time in seconds
|section                           | thruks section
|status                            | connection status of this site
|===========================================


=== GET /logs

lists livestatus logs.
see https://www.naemon.io/documentation/usersguide/livestatus.html#log for details.

=== GET /notifications

lists notifications based on logfiles.
alias for /logs?class=3

=== GET /processinfo

lists livestatus sites status.
see https://www.naemon.io/documentation/usersguide/livestatus.html#status for details.

=== GET /processinfo/stats

lists livestatus sites statistics.
see https://www.naemon.io/documentation/usersguide/livestatus.html#status for details.

=== GET /servicegroups

lists livestatus servicegroups.
see https://www.naemon.io/documentation/usersguide/livestatus.html#servicegroups for details.

=== GET /servicegroups/<name>

lists servicegroups for given name.
alias for /servicegroups?name=<name>

=== POST /servicegroups/<name>/cmd/...

external commands are documented in detail on a separate commands page.
list of supported commands:

 - link:rest_commands.html#post-servicegroupsnamecmddisable_servicegroup_host_checks[disable_servicegroup_host_checks]
 - link:rest_commands.html#post-servicegroupsnamecmddisable_servicegroup_host_notifications[disable_servicegroup_host_notifications]
 - link:rest_commands.html#post-servicegroupsnamecmddisable_servicegroup_passive_host_checks[disable_servicegroup_passive_host_checks]
 - link:rest_commands.html#post-servicegroupsnamecmddisable_servicegroup_passive_svc_checks[disable_servicegroup_passive_svc_checks]
 - link:rest_commands.html#post-servicegroupsnamecmddisable_servicegroup_svc_checks[disable_servicegroup_svc_checks]
 - link:rest_commands.html#post-servicegroupsnamecmddisable_servicegroup_svc_notifications[disable_servicegroup_svc_notifications]
 - link:rest_commands.html#post-servicegroupsnamecmdenable_servicegroup_host_checks[enable_servicegroup_host_checks]
 - link:rest_commands.html#post-servicegroupsnamecmdenable_servicegroup_host_notifications[enable_servicegroup_host_notifications]
 - link:rest_commands.html#post-servicegroupsnamecmdenable_servicegroup_passive_host_checks[enable_servicegroup_passive_host_checks]
 - link:rest_commands.html#post-servicegroupsnamecmdenable_servicegroup_passive_svc_checks[enable_servicegroup_passive_svc_checks]
 - link:rest_commands.html#post-servicegroupsnamecmdenable_servicegroup_svc_checks[enable_servicegroup_svc_checks]
 - link:rest_commands.html#post-servicegroupsnamecmdenable_servicegroup_svc_notifications[enable_servicegroup_svc_notifications]
 - link:rest_commands.html#post-servicegroupsnamecmdschedule_servicegroup_host_downtime[schedule_servicegroup_host_downtime]
 - link:rest_commands.html#post-servicegroupsnamecmdschedule_servicegroup_svc_downtime[schedule_servicegroup_svc_downtime]

=== GET /servicegroups/<name>/config

Returns configuration for given servicegroup.
You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#servicegroup

=== POST /servicegroups/<name>/config

Replace servicegroup configuration completely, use PATCH to only update specific attributes.

=== PATCH /servicegroups/<name>/config

Update servicegroup configuration partially.

=== DELETE /servicegroups/<name>/config

Deletes given servicegroup from configuration.

=== GET /servicegroups/<name>/outages

list of outages for this servicegroup.

Optional arguments:

  * type              - both | hosts | services
  * timeperiod        - last24hours | lastmonth | thismonth | ...
  * start             - unix timestamp
  * end               - unix timestamp
  * withdowntimes     - 0/1 wheter downtimes should count as outages
  * includesoftstates - 0/1 wheter soft states should be used as well

[options="header"]
|===========================================
|Attribute                         | Description
|class                             | host/service status
|duration                          | outage duration in seconds
|end                               | unix timestamp of outage end
|host                              | host name
|in_downtime                       | 0/1 flag wether this outage is in a downtime
|plugin_output                     | last plugin output during outage
|service                           | service description (only for service outages)
|start                             | unix timestamp of outage start
|type                              | log entry type
|===========================================


=== GET /servicegroups/<name>/stats

hash of livestatus servicegroup statistics.
alias for /services/stats?service_groups[gte]=<name>

=== GET /services

lists livestatus services.
see https://www.naemon.io/documentation/usersguide/livestatus.html#services for details.
there is an alias /services.

=== GET /services/<host>/<service>

lists services for given host and name.
alias for /services?host_name=<host_name>&description=<service>

=== POST /services/<host>/<service>/cmd/...

external commands are documented in detail on a separate commands page.
list of supported commands:

 - link:rest_commands.html#post-serviceshostservicecmdacknowledge_svc_problem[acknowledge_svc_problem]
 - link:rest_commands.html#post-serviceshostservicecmdacknowledge_svc_problem_expire[acknowledge_svc_problem_expire]
 - link:rest_commands.html#post-serviceshostservicecmdadd_svc_comment[add_svc_comment]
 - link:rest_commands.html#post-serviceshostservicecmdchange_custom_svc_var[change_custom_svc_var]
 - link:rest_commands.html#post-serviceshostservicecmdchange_max_svc_check_attempts[change_max_svc_check_attempts]
 - link:rest_commands.html#post-serviceshostservicecmdchange_normal_svc_check_interval[change_normal_svc_check_interval]
 - link:rest_commands.html#post-serviceshostservicecmdchange_retry_svc_check_interval[change_retry_svc_check_interval]
 - link:rest_commands.html#post-serviceshostservicecmdchange_svc_check_timeperiod[change_svc_check_timeperiod]
 - link:rest_commands.html#post-serviceshostservicecmdchange_svc_modattr[change_svc_modattr]
 - link:rest_commands.html#post-serviceshostservicecmdchange_svc_notification_timeperiod[change_svc_notification_timeperiod]
 - link:rest_commands.html#post-serviceshostservicecmddel_active_service_downtimes[del_active_service_downtimes]
 - link:rest_commands.html#post-serviceshostservicecmddel_all_svc_comments[del_all_svc_comments]
 - link:rest_commands.html#post-serviceshostservicecmddel_comment[del_comment]
 - link:rest_commands.html#post-serviceshostservicecmddel_downtime[del_downtime]
 - link:rest_commands.html#post-serviceshostservicecmddelay_svc_notification[delay_svc_notification]
 - link:rest_commands.html#post-serviceshostservicecmddisable_passive_svc_checks[disable_passive_svc_checks]
 - link:rest_commands.html#post-serviceshostservicecmddisable_svc_check[disable_svc_check]
 - link:rest_commands.html#post-serviceshostservicecmddisable_svc_event_handler[disable_svc_event_handler]
 - link:rest_commands.html#post-serviceshostservicecmddisable_svc_flap_detection[disable_svc_flap_detection]
 - link:rest_commands.html#post-serviceshostservicecmddisable_svc_notifications[disable_svc_notifications]
 - link:rest_commands.html#post-serviceshostservicecmdenable_passive_svc_checks[enable_passive_svc_checks]
 - link:rest_commands.html#post-serviceshostservicecmdenable_svc_check[enable_svc_check]
 - link:rest_commands.html#post-serviceshostservicecmdenable_svc_event_handler[enable_svc_event_handler]
 - link:rest_commands.html#post-serviceshostservicecmdenable_svc_flap_detection[enable_svc_flap_detection]
 - link:rest_commands.html#post-serviceshostservicecmdenable_svc_notifications[enable_svc_notifications]
 - link:rest_commands.html#post-serviceshostservicecmdprocess_service_check_result[process_service_check_result]
 - link:rest_commands.html#post-serviceshostservicecmdremove_svc_acknowledgement[remove_svc_acknowledgement]
 - link:rest_commands.html#post-serviceshostservicecmdschedule_forced_svc_check[schedule_forced_svc_check]
 - link:rest_commands.html#post-serviceshostservicecmdschedule_svc_check[schedule_svc_check]
 - link:rest_commands.html#post-serviceshostservicecmdschedule_svc_downtime[schedule_svc_downtime]
 - link:rest_commands.html#post-serviceshostservicecmdsend_custom_svc_notification[send_custom_svc_notification]
 - link:rest_commands.html#post-serviceshostservicecmdset_svc_notification_number[set_svc_notification_number]
 - link:rest_commands.html#post-serviceshostservicecmdstart_obsessing_over_svc[start_obsessing_over_svc]
 - link:rest_commands.html#post-serviceshostservicecmdstop_obsessing_over_svc[stop_obsessing_over_svc]

=== GET /services/<host>/<service>/commandline

displays commandline for check command of given services.

[options="header"]
|===========================================
|Attribute                         | Description
|check_command                     | name of the check_command including arguments
|command_line                      | full expanded command line (if possible)
|error                             | contains the error if expanding failed for some reason
|host_name                         | host name
|peer_key                          | backend id when having multiple sites connected
|service_description               | service name
|===========================================


=== GET /services/<host>/<service>/config

Returns configuration for given service.
You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#service

=== POST /services/<host>/<service>/config

Replace service configuration completely, use PATCH to only update specific attributes.

=== PATCH /services/<host>/<service>/config

Update service configuration partially.

=== DELETE /services/<host>/<service>/config

Deletes given service from configuration.

=== GET /services/<host>/<service>/outages

list of outages for this service.

Optional arguments:

  * type              - both | hosts | services
  * timeperiod        - last24hours | lastmonth | thismonth | ...
  * start             - unix timestamp
  * end               - unix timestamp
  * withdowntimes     - 0/1 wheter downtimes should count as outages
  * includesoftstates - 0/1 wheter soft states should be used as well

[options="header"]
|===========================================
|Attribute                         | Description
|class                             | host/service status
|duration                          | outage duration in seconds
|end                               | unix timestamp of outage end
|host                              | host name
|in_downtime                       | 0/1 flag wether this outage is in a downtime
|plugin_output                     | last plugin output during outage
|service                           | service description (only for service outages)
|start                             | unix timestamp of outage start
|type                              | log entry type
|===========================================


=== GET /services/outages

list of outages for all services.

Optional arguments:

  * type              - both | hosts | services
  * timeperiod        - last24hours | lastmonth | thismonth | ...
  * start             - unix timestamp
  * end               - unix timestamp
  * withdowntimes     - 0/1 wheter downtimes should count as outages
  * includesoftstates - 0/1 wheter soft states should be used as well

[options="header"]
|===========================================
|Attribute                         | Description
|class                             | host/service status
|duration                          | outage duration in seconds
|end                               | unix timestamp of outage end
|host                              | host name
|in_downtime                       | 0/1 flag wether this outage is in a downtime
|plugin_output                     | last plugin output during outage
|service                           | service description (only for service outages)
|start                             | unix timestamp of outage start
|type                              | log entry type
|===========================================


=== GET /services/stats

livestatus service statistics.

[options="header"]
|===========================================
|Attribute                         | Description
|active_checks_disabled_active     | number of active services which have active checks disabled
|active_checks_disabled_passive    | number of passive services which have active checks disabled
|critical                          | number of critical services
|critical_and_ack                  | number of critical services which are acknowledged
|critical_and_disabled_active      | number of active critical services which have active checks disabled
|critical_and_disabled_passive     | number of passive critical services which have active checks disabled
|critical_and_scheduled            | number of critical services which are in a scheduled downtime
|critical_and_unhandled            | number of unhandled critical services
|critical_on_down_host             | number of unhandled critical services on down hosts
|eventhandler_disabled             | number of services with eventhandlers disabled
|flapping                          | number of flapping services
|flapping_disabled                 | number of services with flapping detection disabled
|notifications_disabled            | number of services with notifications disabled
|ok                                | number of ok services
|ok_and_disabled_active            | number of active ok services which have active checks disabled
|ok_and_disabled_passive           | number of passive ok services which have active checks disabled
|ok_and_scheduled                  | number of ok services which are in a scheduled downtime
|passive_checks_disabled           | number of services which do not accept passive check results
|pending                           | number of pending services
|pending_and_disabled              | number of pending services with active checks disabled
|pending_and_scheduled             | number of pending services which are in a scheduled downtime
|plain_critical                    | number of critical services which are not acknowleded or in a downtime
|plain_ok                          | number of ok services which are not acknowleded or in a downtime
|plain_pending                     | number of pending services which are not acknowleded or in a downtime
|plain_unknown                     | number of unknown services which are not acknowleded or in a downtime
|plain_warning                     | number of warning services which are not acknowleded or in a downtime
|total                             | total number of services
|total_active                      | total number of active services
|total_passive                     | total number of passive services
|unknown                           | number of unknown services
|unknown_and_ack                   | number of unknown services which are acknowledged
|unknown_and_disabled_active       | number of active unknown services which have active checks disabled
|unknown_and_disabled_passive      | number of passive unknown services which have active checks disabled
|unknown_and_scheduled             | number of unknown services which are in a scheduled downtime
|unknown_and_unhandled             | number of unhandled unknown services
|unknown_on_down_host              | number of unhandled unknown services on down hosts
|warning                           | number of warning services
|warning_and_ack                   | number of warning services which are acknowledged
|warning_and_disabled_active       | number of active warning services which have active checks disabled
|warning_and_disabled_passive      | number of passive warning services which have active checks disabled
|warning_and_scheduled             | number of warning services which are in a scheduled downtime
|warning_and_unhandled             | number of unhandled warning services
|warning_on_down_host              | number of unhandled warning services on down hosts
|===========================================


=== GET /services/totals

livestatus service totals statistics.
its basically a reduced set of /services/stats.

[options="header"]
|===========================================
|Attribute                         | Description
|critical                          | number of critical services
|critical_and_unhandled            | number of critical services which are neither acknowledged nor in scheduled downtime
|ok                                | number of ok services
|pending                           | number of pending services
|total                             | total number of services
|unknown                           | number of unknown services
|unknown_and_unhandled             | number of unknown services which are neither acknowledged nor in scheduled downtime
|warning                           | number of warning services
|warning_and_unhandled             | number of warning services which are neither acknowledged nor in scheduled downtime
|===========================================


=== GET /sites

lists configured backends

[options="header"]
|===========================================
|Attribute                         | Description
|addr                              | address for this connection
|connected                         | flag wether sites is connected (1) or not (0)
|federation_addr                   | contains the real address if using federation
|federation_key                    | contains the real peer key if using federation
|federation_name                   | contains the real name if using federation
|federation_type                   | contains the real backend type if using federation
|id                                | id for this backend
|last_error                        | error message if backend is not connected
|localtime                         | current local unix timestamp of thruk host
|name                              | name of the backend
|section                           | section name
|status                            | 0 (OK), 1 (DOWN)
|type                              | type of the backend
|===========================================


=== POST /system/cmd/...

external commands are documented in detail on a separate commands page.
list of supported commands:

 - link:rest_commands.html#post-systemcmdchange_global_host_event_handler[change_global_host_event_handler]
 - link:rest_commands.html#post-systemcmdchange_global_svc_event_handler[change_global_svc_event_handler]
 - link:rest_commands.html#post-systemcmddel_downtime_by_host_name[del_downtime_by_host_name]
 - link:rest_commands.html#post-systemcmddel_downtime_by_hostgroup_name[del_downtime_by_hostgroup_name]
 - link:rest_commands.html#post-systemcmddel_downtime_by_start_time_comment[del_downtime_by_start_time_comment]
 - link:rest_commands.html#post-systemcmddel_host_comment[del_host_comment]
 - link:rest_commands.html#post-systemcmddel_host_downtime[del_host_downtime]
 - link:rest_commands.html#post-systemcmddel_svc_comment[del_svc_comment]
 - link:rest_commands.html#post-systemcmddel_svc_downtime[del_svc_downtime]
 - link:rest_commands.html#post-systemcmddisable_event_handlers[disable_event_handlers]
 - link:rest_commands.html#post-systemcmddisable_flap_detection[disable_flap_detection]
 - link:rest_commands.html#post-systemcmddisable_host_freshness_checks[disable_host_freshness_checks]
 - link:rest_commands.html#post-systemcmddisable_notifications[disable_notifications]
 - link:rest_commands.html#post-systemcmddisable_performance_data[disable_performance_data]
 - link:rest_commands.html#post-systemcmddisable_service_freshness_checks[disable_service_freshness_checks]
 - link:rest_commands.html#post-systemcmdenable_event_handlers[enable_event_handlers]
 - link:rest_commands.html#post-systemcmdenable_flap_detection[enable_flap_detection]
 - link:rest_commands.html#post-systemcmdenable_host_freshness_checks[enable_host_freshness_checks]
 - link:rest_commands.html#post-systemcmdenable_notifications[enable_notifications]
 - link:rest_commands.html#post-systemcmdenable_performance_data[enable_performance_data]
 - link:rest_commands.html#post-systemcmdenable_service_freshness_checks[enable_service_freshness_checks]
 - link:rest_commands.html#post-systemcmdread_state_information[read_state_information]
 - link:rest_commands.html#post-systemcmdrestart_process[restart_process]
 - link:rest_commands.html#post-systemcmdrestart_program[restart_program]
 - link:rest_commands.html#post-systemcmdsave_state_information[save_state_information]
 - link:rest_commands.html#post-systemcmdshutdown_process[shutdown_process]
 - link:rest_commands.html#post-systemcmdshutdown_program[shutdown_program]
 - link:rest_commands.html#post-systemcmdstart_accepting_passive_host_checks[start_accepting_passive_host_checks]
 - link:rest_commands.html#post-systemcmdstart_accepting_passive_svc_checks[start_accepting_passive_svc_checks]
 - link:rest_commands.html#post-systemcmdstart_executing_host_checks[start_executing_host_checks]
 - link:rest_commands.html#post-systemcmdstart_executing_svc_checks[start_executing_svc_checks]
 - link:rest_commands.html#post-systemcmdstart_obsessing_over_host_checks[start_obsessing_over_host_checks]
 - link:rest_commands.html#post-systemcmdstart_obsessing_over_svc_checks[start_obsessing_over_svc_checks]
 - link:rest_commands.html#post-systemcmdstop_accepting_passive_host_checks[stop_accepting_passive_host_checks]
 - link:rest_commands.html#post-systemcmdstop_accepting_passive_svc_checks[stop_accepting_passive_svc_checks]
 - link:rest_commands.html#post-systemcmdstop_executing_host_checks[stop_executing_host_checks]
 - link:rest_commands.html#post-systemcmdstop_executing_svc_checks[stop_executing_svc_checks]
 - link:rest_commands.html#post-systemcmdstop_obsessing_over_host_checks[stop_obsessing_over_host_checks]
 - link:rest_commands.html#post-systemcmdstop_obsessing_over_svc_checks[stop_obsessing_over_svc_checks]

=== GET /thruk

hash of basic information about this thruk instance

[options="header"]
|===========================================
|Attribute                         | Description
|rest_version                      | rest api version
|thruk_version                     | thruk version
|thruk_release_date                | thruk release date
|localtime                         | current server unix timestamp / epoch
|project_root                      | thruk root folder
|etc_path                          | configuration folder
|var_path                          | variable data folder
|extra_version                     | might contain omd version
|extra_link                        | contains link from extra_versions product
|===========================================


=== GET /thruk/api_keys

lists api keys

[options="header"]
|===========================================
|Attribute                         | Description
|comment                           | comment of this api key
|created                           | unixtimestamp of when the key was created
|digest                            | used hash algorithm
|file                              | path to stored file
|force_user                        | super user keys can enforce a specific user
|hashed_key                        | hashed private key
|last_from                         | ip address of last usage
|last_used                         | unixtimestamp of last usage
|roles                             | list of roles this key is limited too
|superuser                         | flag wether this a global superuser key and not bound to a specific user
|user                              | username of key owner
|===========================================


=== POST /thruk/api_keys

create new api key.

Optional arguments:

  * comment
  * superuser  (flag to create superuser api key)
  * username   (requires admin privileges, assigns key to specific user)
  * roles      (restrict roles to given list)
  * force_user (sets username in combination with super user flag)

=== GET /thruk/api_keys/<id>

alias for /thruk/api_keys?hashed_key=<id>

=== DELETE /thruk/api_keys/<id>

remove key for given id.

=== GET /thruk/bp

lists business processes.

[options="header"]
|===========================================
|Attribute                         | Description
|affected_peers                    | list of backend ids used for the last calculation
|bp_backend                        | id of backend which hosts the business process
|create_host_object                | 0 - do no create a host object, 1 - create naemon host object
|draft                             | flag wether this is a draft only
|filter                            | list of enabled filters
|id                                | primary id
|last_check                        | timestamp of last check result submited
|last_state_change                 | timestamp of last state change
|name                              | name of this business proces
|nodes                             | all nodes of this business process
|rankDir                           | flag wheter this business process is horizontal or vertical
|state_type                        | flag if this business process uses hard or soft state types
|status                            | current status
|status_text                       | current status text
|template                          | naemon template used for the generated object
|time                              | calculation duration
|===========================================


=== POST /thruk/bp

create new business process.

=== GET /thruk/bp/<nr>

business processes for given number.
alias for /thruk/bp?id=<nr>

=== POST /thruk/bp/<nr>

update business processes configuration for given number.

=== PATCH /thruk/bp/<nr>

update business processes configuration partially for given number.

=== DELETE /thruk/bp/<nr>

remove business processes for given number.

=== GET /thruk/broadcasts

lists broadcasts

[options="header"]
|===========================================
|Attribute                         | Description
|annotation                        | annotation icon for this broadcast
|author                            | author of the broadcast
|authoremail                       | authors E-Mail address, mainly used as macro
|contactgroups                     | list of contactgroups if broadcast should be limited to specific groups
|contacts                          | list of contacts if broadcast should be limited to specific contacts
|expires                           | expire date after which the broadcast won't be displayed anymore
|expires_ts                        | expire data as unix timestamp
|file                              | filename
|frontmatter                       | hash list of extraceted frontmatter variables
|hide_before                       | do not show broadcast before this date
|hide_before_ts                    | hide_before as unix timestamp
|loginpage                         | flag wether broadcast should be displayed on the loginpage as well
|macros                            | hash list of macros
|name                              | name of this broadcast, mostly used for templates
|panorama                          | flag wether broadcast should be displayed on panorama dashboards
|raw_text                          | raw broadcast text
|template                          | flag wether this broadcast is a template
|text                              | processed broadcast message
|===========================================


=== POST /thruk/broadcasts

create new broadcast.

=== GET /thruk/broadcasts/<file>

alias for /thruk/broadcasts?file=<file>

=== POST /thruk/broadcasts/<file>

update entire broadcast for given file.

=== PATCH /thruk/broadcasts/<file>

update attributes for given broadcast.

=== DELETE /thruk/broadcasts/<file>

remove broadcast for given file.

=== GET /thruk/cluster

lists cluster nodes

[options="header"]
|===========================================
|Attribute                         | Description
|hostname                          | host name of the cluster node
|last_contact                      | timestamp of last successful contact
|last_error                        | text of last error message
|maintenance                       | Flag whether this node is in maintenance mode
|node_id                           | internal id for this node
|node_url                          | url to access this node directly
|pids                              | list of current process ids of this node
|response_time                     | response time in seconds
|version                           | version information of this node
|===========================================


=== GET /thruk/cluster/<id>

return cluster state for given node.

See `/thruk/cluster/` for the description of the attributes.

=== GET /thruk/cluster/heartbeat

should not be used, use POST method instead

=== POST /thruk/cluster/heartbeat

send cluster heartbeat to all other nodes

=== POST /thruk/cluster/restart

restarts all cluster nodes sequentially

=== GET /thruk/config

lists configuration information

=== GET /thruk/jobs

lists thruk jobs.

[options="header"]
|===========================================
|Attribute                         | Description
|cmd                               | the executed command line or perl code
|end                               | timestamp when the job finished
|forward                           | url to forward when the job is done
|host_id                           | thruk node id this job is run on
|host_name                         | hostname of the node
|id                                | job id
|is_running                        | flag whether the job is still running
|message                           | current status text
|percent                           | percent of completion
|perl_res                          | contains the perl result in case this was a perl job
|pid                               | process id
|rc                                | return code
|remaining                         | remaining seconds for the job to complete
|show_output                       | flag whether output console will be displayed
|start                             | timestamp when the job started
|stderr                            | stderr output
|stdout                            | stdout output
|time                              | duration in seconds
|user                              | username of the owner
|===========================================


=== GET /thruk/jobs/<id>

get thruk job status for given id.
alias for /thruk/jobs?id=<id>

=== GET /thruk/logcache/stats

lists logcache statistics

[options="header"]
|===========================================
|Attribute                         | Description
|cache_version                     | db schema version
|compact_duration                  | duration of last compact run in seconds
|compact_till                      | timestamp marker where last compact run finished
|data_size                         | used size of data in bytes
|enabled                           | flag wether logcache is enabled for this backend or not
|index_size                        | used size of index in bytes
|items                             | number of items/rows
|key                               | peer key
|last_compact                      | timestamp of last compact run
|last_entry                        | timestamp of last log entry
|last_reorder                      | timestamp of last optimize run
|last_update                       | timestamp of last update run
|mode                              | current lock mode
|name                              | peer name
|reorder_duration                  | duration of last reorder run in seconds
|status                            | human readable status
|update_duration                   | duration of last update run in seconds
|===========================================


=== POST /thruk/logcache/update

runs the logcache delta update.

=== GET /thruk/metrics

alias for /thruk/stats

=== GET /thruk/panorama

lists all panorama dashboards.

[options="header"]
|===========================================
|Attribute                         | Description
|file                              | filename of the dashboard
|file_version                      | version of dashboard format
|id                                | internal id
|maintenance                       | maintenance reason (only if in maintenance mode)
|nr                                | number of the dashboard
|objects                           | number of objects
|panlet_<nr>                       | panlet definition
|readonly                          | flag whether this dashboard is read-only
|scripted                          | flag whether this is a scripted dashboard
|tab                               | structure of global dashboard settings
|ts                                | timestamp of last modification
|user                              | owner of this dashboard
|===========================================


=== GET /thruk/panorama/<nr>

returns panorama dashboard for given number.
alias for /thruk/panorama?nr=<nr>

=== POST /thruk/panorama/<nr>/maintenance

Puts given dashboard into maintenance mode.

Required arguments:

  * text

=== DELETE /thruk/panorama/<nr>/maintenance

removes maintenance mode from given dashboard.

=== GET /thruk/recurring_downtimes

lists recurring downtimes.

[options="header"]
|===========================================
|Attribute                         | Description
|backends                          | list of backends this downtime is used for
|childoptions                      | flag used for the downtime command
|comment                           | comment used for the downtime command
|created_by                        | username who created this downtime
|duration                          | duration in minutes
|edited_by                         | username who last edited this downtime
|error                             | contains the error message if something got wrong with this downtime
|file                              | file number
|fixed                             | flag whether this should create a fixed downtime
|flex_range                        | range in minutes for flexible downtimes
|host                              | list of hostnames
|hostgroup                         | list of hostgroups
|last_changed                      | unix timestamp of last change
|schedule                          | list of schedules
|service                           | list of services
|servicegroup                      | list of servicegroups
|target                            | sets the type of the downtime, ex. host or hostgroup
|===========================================


=== POST /thruk/recurring_downtimes

create new downtime.

=== GET /thruk/recurring_downtimes/<file>

alias for /thruk/recurring_downtimes?file=<file>

=== POST /thruk/recurring_downtimes/<file>

update entire downtime for given file.

=== PATCH /thruk/recurring_downtimes/<file>

update attributes for given downtime.

=== DELETE /thruk/recurring_downtimes/<file>

remove downtime for given file.

=== GET /thruk/reports

list of reports.

[options="header"]
|===========================================
|Attribute                         | Description
|backends                          | list of backends used in this report
|cc                                | email cc address if this report is send by mail
|desc                              | report description
|error                             | contains error messages (optional)
|failed                            | flag wheter the report failed to generate last time
|is_public                         | flag wheter the report is public or not
|name                              | name of the report
|nr                                | number of the report
|params                            | reporting parameters
|permissions                       | user/group permission
|readonly                          | flag wheter the report is read-only
|send_types                        | list of cron entries
|template                          | template of the report
|to                                | email to address if this report is send by mail
|user                              | owner
|===========================================


=== POST /thruk/reports

create new report.

=== GET /thruk/reports/<nr>

report for given number.

[options="header"]
|===========================================
|Attribute                         | Description
|backends                          | list of selected backends.
|cc                                | carbon-copy for report email.
|desc                              | description.
|error                             | contains error messages (optional)
|failed                            | failed flag.
|is_public                         | flag for public reports.
|name                              | name of the report.
|nr                                | primary id.
|params                            | report parameters.
|permissions                       | user/group permission
|readonly                          | readonly flag.
|send_types                        | list of crontab entries.
|template                          | report template.
|to                                | email address the report email.
|user                              | owner of the report.
|===========================================


=== POST /thruk/reports/<nr>

update entire report for given number.

=== PATCH /thruk/reports/<nr>

update attributes for given number.

=== DELETE /thruk/reports/<nr>

remove report for given number.

=== POST /thruk/reports/<nr>/generate

generate report for given number.

=== GET /thruk/reports/<nr>/report

return the actual report file in binary format.

=== GET /thruk/sessions

lists thruk sessions.

[options="header"]
|===========================================
|Attribute                         | Description
|active                            | timestamp when session was last time used
|address                           | remote address of user
|digest                            | used hash algorithm
|fake                              | flag whether this is a fake session or not
|file                              | file name the session data file
|hashed_key                        | hashed session id
|roles                             | extra session roles
|username                          | username of this session
|===========================================


=== GET /thruk/sessions/<id>

get thruk sessions status for given id.
alias for /thruk/sessions?id=<id>

=== GET /thruk/stats

lists thruk statistics.

[options="header"]
|===========================================
|Attribute                         | Description
|business_process_duration_seconds | business process calculation duration in seconds
|business_process_last_update      | timestamp of last business process calculation
|business_process_total            | total number of business processes
|business_process_worker_total     | total number of worker processes used to calculate business processes
|sessions_active_5min_total        | total number of active thruk sessions (active during the last 5 minutes)
|sessions_total                    | total number of thruk sessions
|sessions_uniq_user_5min_total     | total number of uniq users active during the last 5 minutes
|sessions_uniq_user_total          | total number of uniq users
|users_locked_total                | total number of locked thruk users
|users_total                       | total number of thruk users
|===========================================


=== GET /thruk/users

lists thruk user profiles.

[options="header"]
|===========================================
|Attribute                         | Description
|alias                             | alias name
|can_submit_commands               | flag wether this account is allowed to submit commands
|email                             | email address
|groups                            | list of contactgroups
|has_thruk_profile                 | flag wether this account has a thruk profile or not
|id                                | username
|last_login                        | timestamp of last successfull login
|locked                            | flag wether account is locked or not
|roles                             | list of roles for this user
|tz                                | users selected timezone
|===========================================


=== GET /thruk/users/<id>

get thruk profile for given user.
alias for /thruk/users?id=<id>

=== GET /thruk/whoami

show current profile information.
alias for /thruk/users?id=<id>

=== GET /timeperiods

lists livestatus timeperiods.
see https://www.naemon.io/documentation/usersguide/livestatus.html#timeperiods for details.

=== GET /timeperiods/<name>

lists timeperiods for given name.
alias for /timeperiods?name=<name>

=== GET /timeperiods/<name>/config

Returns configuration for given timeperiod.
You will find available attributes here: http://www.naemon.io/documentation/usersguide/objectdefinitions.html#timeperiod

=== POST /timeperiods/<name>/config

Replace timeperiod configuration completely, use PATCH to only update specific attributes.

=== PATCH /timeperiods/<name>/config

Update timeperiods configuration partially.

=== DELETE /timeperiods/<name>/config

Deletes given timeperiod from configuration.

