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


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

Read more about the link:rest.html[REST API] itself. This page contains
some useful reallife examples.

=== Simple Host List

Fetch list of all host names:

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

or by curl:

------
  %> curl -g 'http://user:password@localhost/thruk/r/csv/hosts?columns=name'
------


=== Notifications Per Hour Group by Site

List total number of notifications send in the last 60 minutes grouped by backend name:

------
  %> thruk r '/notifications?time[gt]=-60m&columns=count(*):notifications_per_hour,peer_name'
------

=== Sending Commands

==== Add Service Downtime

Putting a service into downtime can be done by either the `thruk` cli tool:

------
  %> thruk r -d "start_time=now" -d "end_time=+60m" -d "comment_data='downtime comment'" '/services/<host>/<svc>/cmd/schedule_svc_downtime'
------

or by sending a http request, for example with curl:

------
  %> curl -d "start_time=now" --data-urlencode "end_time=+60m" -d "comment_data='downtime comment'" http://0:3000/thruk/r/services/<host>/<svc>/cmd/schedule_svc_downtime
------

Note that you don't have to set all parameters, only the required ones are
necessary. You can use relative arguments for the start- and end-time. For
example `now` will be replaced with the current timestamp while `+60m` will
be 60 minutes in the future.

Read more about link:rest_commands.html#relative-timestamps[relative timestamps].

`start_time` is optional and will be set to the current timestamp.

`end_time` is optional as well and will be set to the default `downtime_duration`.

This leaves a single required argument with the downtime comment:

------
  %> curl -d "comment_data='downtime comment'" http://0:3000/thruk/r/services/<host>/<svc>/cmd/schedule_svc_downtime
------

==== Send Any Command

To avoid escaping issues, there is a generic command endpoint `/cmd` which can be used
to send any command.

------
    %> curl -H "X-Thruk-Auth-Key: ****" \
            -d "cmd=acknowledge_svc_problem" \
            -d "host=hostname" \
            -d "service=servicedescription" \
            -d "comment_data=test" \
          'http://localhost/thruk/r/cmd'
------

=== Grouping

List sessions which had been active within the last 10minutes:

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

=== Create new Host Object

To create objects via the config tool you can use the generic /config/objects
endpoint like this:

------
    %> curl -H "X-Thruk-Auth-Key: ****" \
            -X POST \
            --header "Content-Type: application/json" \
            -d '{":TYPE": "host", ":FILE":"testhosts.cfg","name":"testhost123"}' \
            http://localhost/thruk/r/config/objects
------
