← Back to Docs

REST API

This document describes the Monibot REST API. The API has resource-oriented URLs, accepts form-encoded request bodies, returns JSON responses, and uses standard HTTP response codes.

Table Of Contents


Authorization

For authorization, each API request must include an Authorization header with your API Key. You can find your API Key in your account profile: Log into your account, open your account's 'Profile' page and click 'Show API Key'.
And please make sure to keep your API Key secret at all times.



Endpoints


GET Ping

The GET /ping endpoint is used to test the API access. 
$ curl https://monibot.io/api/ping \
    -H "Authorization: Bearer $MONIBOT_API_KEY"
Response: 
{ "ok": true }

GET Watchdogs

The GET /watchdogs endpoint is used to list watchdogs. 
$ curl -X POST https://monibot.io/api/watchdogs \
    -H "Authorization: Bearer $MONIBOT_API_KEY"
Response: 
[
    {
        "id": "891901913078071734913841349314cd",
        "intervalMillis": 7200000,
        "name": "DB Backup"
    },
    {
        "id": "74983975836491364938649139461937",
        "intervalMillis": 3600000,
        "name": "CSV Export"
    }
]
The endpoint returns a list of watchdog objects:
  • id: The id of the watchdog.
  • intervalMillis: The expected heartbeat interval in milliseconds.
  • name: The name of the watchdog.

GET Watchdog

The GET /watchdog/:id endpoint is used to get a watchdog. 
$ curl -X POST https://monibot.io/api/watchdog/$WATCHDOG_ID \
    -H "Authorization: Bearer $MONIBOT_API_KEY"
Response: 
{
    "id": "891901913078071734913841349314cd",
    "intervalMillis": 7200000,
    "name": "DB Backup"
}

POST Watchdog Heartbeat

The POST /watchdog/:id/heartbeat endpoint is used to send a watchdog heartbeat. 
$ curl -X POST https://monibot.io/api/watchdog/$WATCHDOG_ID/heartbeat \
    -H "Authorization: Bearer $MONIBOT_API_KEY"
Response: 
{ "ok": true }

GET Machines

The GET /machines endpoint is used to list machines. 
$ curl -X POST https://monibot.io/api/machines \
    -H "Authorization: Bearer $MONIBOT_API_KEY"
Response: 
[
    {
        "id": "00000003078071734913841349314cd",
        "name": "Web Server"
    },
    {
        "id": "8a87b49c56d91ff574a97d56e14aa796",
        "name": "DB Node 1"
    }
]
The endpoint returns a list of machine objects:
  • id: The id of the machine.
  • name: The name of the machine.

GET Machine

The GET /machine/:id endpoint is used to get a machine. 
$ curl -X POST https://monibot.io/api/machine/$MACHINE_ID \
    -H "Authorization: Bearer $MONIBOT_API_KEY"
Response: 
{
    "id": "8a87b49c56d91ff574a97d56e14aa796",
    "name": "Web Server"
}

POST Machine Sample

The POST /machine/:id/sample endpoint is used to send a resource usage sample for a machine. 
$ curl -X POST https://monibot.io/api/machine/$MACHINE_ID/sample \
    -H "Authorization: Bearer $MONIBOT_API_KEY" \
    -d "tstamp=1698857664378" \
    -d "load1=0.2" \
    -d "load5=0.3" \
    -d "load15=0.8" \
    -d "cpu=5" \
    -d "mem=12" \
    -d "disk=32" \
    -d "diskReads=1024" \
    -d "diskWrites=1024" \
    -d "netRecv=1024" \
    -d "netSend=1024"
Data:
  • tstamp: The current machine timestamp in unix epoch milliseconds, i.e. the number of milliseconds since 1970-01-01T00:00:00 UTC.
  • load1: The loadavg for 1 minute. A non-negative floating-point number.
  • load5: The loadavg for 5 minutes. A non-negative floating-point number.
  • load15: The loadavg for 15 minutes. A non-negative floating-point number.
  • cpu: The current CPU usage in percent. An integer number in the range [0;100].
  • mem: The current memory (RAM) usage in percent. An integer number in the range [0;100].
  • disk: The current disk usage in percent. An integer number in the range [0;100].
  • diskReads: The number of disk sectors read since last invocation. An non-negative integer number.
  • diskWrites: The number of disk sectors written since last invocation. An non-negative integer number.
  • netRecv: The number of network bytes received since last invocation. An non-negative integer number.
  • netSend: The number of network bytes sent since last invocation. An non-negative integer number.
Response: 
{ "ok": true }
Notes:
  • While it is possible to invoke this endpoint via curl, we recommend using the moni command line tool to send machine resource samples to Monibot.

POST Machine Text

The POST /machine/:id/text endpoint is used to send an arbitrary text for a machine. It can be used to send command outputs for a machine. 
$ curl -X POST https://monibot.io/api/machine/$MACHINE_ID/text \
    -H "Authorization: Bearer $MONIBOT_API_KEY" \
    --data-urlencode text@some-file.txt
Data:
  • text: An arbitrary text. Max. length is 200 KB
Response: 
{ "ok": true }

GET Metrics

The GET /metrics endpoint is used to list metrics. 
$ curl -X POST https://monibot.io/api/metrics \
    -H "Authorization: Bearer $MONIBOT_API_KEY"
Response: 
[
    {
        "id": "81389074981349139137649736497163",
        "name": "cpx11 upgradable",
        "type": 1
    },
    {
        "id": "33987139139739039039028361934134",
        "name": "mietspiegel.com requests",
        "type": 0
    }
]
The endpoint returns a list of metric objects:
  • id: The id of the metric.
  • name: The name of the metric.
  • type: The metric type. 0 (Counter), 1 (Gauge) or 2 (Histogram).

GET Metric

The GET /metric/:id endpoint is used to get a metric. 
$ curl -X POST https://monibot.io/api/metric/$METRIC_ID \
    -H "Authorization: Bearer $MONIBOT_API_KEY"
Response: 
{
    "id": "8a87b49c56d91ff574a97d56e14aa796",
    "name": "Web Server"
}

POST Metric Increment

The POST /metric/:id/inc endpoint is used to increment a 'counter' metric. 
$ curl -X POST https://monibot.io/api/metric/$METRIC_ID/inc \
    -H "Authorization: Bearer $MONIBOT_API_KEY" \
    -d "value=5"
Data:
  • value: The increment value. A non-negative 64-bit integer number.
Response: 
{ "ok": true }

POST Metric Set

The POST /metric/:id/set endpoint is used to set a 'gauge' metric. 
$ curl -X POST https://monibot.io/api/metric/$METRIC_ID/set \
    -H "Authorization: Bearer $MONIBOT_API_KEY" \
    -d "value=962"
Data:
  • value: The new gauge value. A non-negative integer number.
Response: 
{ "ok": true }

POST Metric Values

The POST /metric/:id/values endpoint is used to add values for a 'histogram' metric. 
$ curl -X POST https://monibot.io/api/metric/$METRIC_ID/values \
    -H "Authorization: Bearer $MONIBOT_API_KEY" \
    -d "values=0:2,1,2:3,17,18:10"
Data:
  • values: The histogram values. Values is a non-empty comma-separated list of 'value:count' pairs. The value part must be a non-negative 64-bit integer value. The count part is a integer greater or equal to 1. The default count, if left out, is 1. So, values "0:1,1:1,2:1" and "0,1,2" are semantically the same.
Response: 
{ "ok": true }


Tools and Libraries

While all API endpoints can be accessed via curl, as shown above, there are other (often better) ways to access the API.

moni

The moni command line tool is specifically designed for accessing the Monibot REST API. It provides an easy command line interface, retries requests if they fail, and provides a automated way to collect machine resource usage data on linux machines. You can read more about the moni tool here: /docs/moni-tool.

Golang SDK

If you develop in Golang, we have a Golang SDK. It's open-source, easy to use and hosted on github: https://github.com/cvilsmeier/monibot-go. The SDK is specifically designed to be embedded in your webapps. With the SDK, you can programmatically send metrics data, watchdog heartbeats, machine usage samples, and so on. Using the SDK, you can even implement your own CLI tool (like moni, which is also built with the SDK).

Any HTTP library

If you develop in Java, Python, Ruby, PHP, or any other programming language, you can use the language's included HTTP client library (or any third-party HTTP library) to access the Monibot REST API. The API uses standard HTTP conventions, so any HTTP library in any programming language will work.



Rate Limits

Currently we haven't rate-limited 'GET' endpoints, but that may change in the future.

'POST' endpoints are limited to approximately one invocation every five minutes. Short bursts are OK. For longer bursts, we may reject API requests to protect our service. In that case, each endpoint sends a '429 - Too Many Requests' response.









English

Deutsch

Contact


Made and hosted in Germany
© 2024 monibot.io

Terms - Privacy - Imprint