API

API endpoint for versions 0.8.0+ is: /api/servers/{API_VERSION}.

All endpoints currently require authorization in the form of an API key. This is returned when you add a server to hotpotato.

V2

This version of the API is used from Hot Potato v0.8.0 onwards.

Authentication

Monitoring servers get API keys generated for them once they are added to the Hot Potato database. Servers use these to authenticate themselves when interacting with the REST API.

If an API endpoint requires authentication, the monitoring server must include an Authorization HTTP header, using a custom Apikey authentication scheme, with the API key itself as the provided credentials.

Authorization: Apikey 1a2b3c4d5e6f...

If the monitoring server fails to provide a valid API key in a request that requires one, they will receive an API standard response with an error code of 401 (unauthorised), and an error message providing details in the message field.

POST /heartbeats/create

Send a heartbeat to a server

Example request

POST /heartbeats/create HTTP/1.1
Authorization: apikey s7f6sa8d7g6df8gh76dfsg876dfsg876sdf78g6ds7gf6ds8f67d7s8g8934qysdgkjh389dsf43tog4kdj3lsh3jskcm

Example response

HTTP/1.1 201 Created
Content-Type: text/javascript

{
   "success": true,
   "code": 201,
   "message": null,
   "data": {
      "id": 123345,
      "server_id": 12,
      "recieved_dt": 2018-07-10 02:08:57.717142
   }
}
Request Headers
Status Codes
GET /notifications/get/(int: notification_id)

Get a notification as JSON

Example request

GET /notifications/get/15 HTTP/1.1
Authorization: apikey s7f6sa8d7g6df8gh76dfsg876dfsg876sdf78g6ds7gf6ds8f67d7s8g8934qysdgkjh389dsf43tog4kdj3lsh3jskcm

Example response

HTTP/1.1 200 OK
Content-Type: text/javascript

{
   "success": true,
   "code": 200,
   "message": null,
   "data": {
      "hostname": "host",
      "servicename": "",
      "troublecode": "",
      "displayname": "",
      "output": "",
      "notificationtype": ""
   }
}
Parameters

  • notification_id (int) – notification id

Request Headers
Status Codes
POST /notifications/send

Create a notification and send it to the on-call person.

Example request

POST /notifications/send HTTP/1.1
Authorization: apikey s7f6sa8d7g6df8gh76dfsg876dfsg876sdf78g6ds7gf6ds8f67d7s8g8934qysdgkjh389dsf43tog4kdj3lsh3jskcm

Example response

HTTP/1.1 201 Created
Content-Type: text/javascript

{
   "success": true,
   "code": 200,
   "message": null,
   "data": {
      "tenant_id": 12,
      "user_id": 1,
      "notif_type": "",
      "server_id": 13,
      "server_name": "myserver",
      "trouble_code": "BAD01",
      "hostname": "myhost",
      "display_name": "My host",
      "service_name": "Postgres",
      "state": "Down",
      "output": "...",
      "timestamp": "2018-07-10 02:08:57.717142"
   }
}
Request JSON Object

  • notif_type (string) – the type of notification

  • trouble_code (int) – the issue code

  • hostname (string) – the server’s hostname

  • display_name (string) – the server’s display name

  • service_name (string) – the service name

  • state (string) – a

  • output (string) – a

Status Codes

V1

Deprecated since version 7.0.

This version of the API is used by all versions of Hot Potato up to v0.7.0. Hot Potato v0.8.0 onwards are backwards compatible with this protocol, but the endpoint has been relocated to allow additional REST APIs to be accessible.

To use the version 1 monitoring server API on Hot Potato version 0.7.0 or earlier, configure the Hot Potato client on your monitoring server with an API URL similar to the following: https://hotpotato.example.com/api/v1.

Authentication

Monitoring servers get API keys generated for them once they are added to the Hot Potato database. Servers use these to authenticate themselves when interacting with the REST API.

If an API endpoint requires authentication, the monitoring server must include an apikey JSON field, with the API key itself as the provided credentials.

{
  "apikey": "1a2c3c4d5e6f..."
}

If the monitoring server fails to provide a valid API key in a request that requires one, they will receive an API standard response with an error code of 403 (unauthorised), and an error message providing details as the output.

Notifications

API endpoints for getting and sending notifications.

POST /check/notification

Check if a notification exists

Example response

HTTP/1.1 200 OK
Content-Type: text/plain

true
Request JSON Object

  • id (int) – ID of the notification

Request Headers
Status Codes
POST /add/notification

Create a notification, and send it to the on-call person. The notification is returned in the response body

Request JSON Object

  • notificationtype (string) – Notification type, either service or host.

  • troublecode (string) – Trouble code of the notification.

  • hostname (string) – Hostname of the host being reported on.

  • displayname (string) – Human-readable name of the host.

  • servicename (string) – For service notifications, the name of the service.

  • state (string) – State of the service/host.

  • output (string) – Output from the service host.

  • icingadatetime (datetime) – Timestamp of the notification from the monitoring server.

Request Headers
Status Codes

Heartbeats

API endpoints for interacting with server heartbeats.

Senders

API Endpoints for interacting with sending providers.

Modica

API endpoints for interaction with modica.

POST /modica/mo-messages

Callback for handling incoming SMS messages from Modica.

Request JSON Object

  • id (int) – Provider message ID of the incoming SMS message.

  • source (string) – Contact number of the sender.

  • operator (string) – Operator name.

  • reply-to (int) – Provider message ID of the SMS message the incoming one is responding to.

  • content (string) – Message body.

  • encoding (string) – Message encoding (optional, included only when the message contains binary data)

POST /modica/dlr-status

Call back for handling delivery status receipts from Modica.

Request JSON Object

  • message_id (int) – Provider message ID of the outgoing message being reported on.

  • status (enum) – Message status from Modica. Possible values: ‘submitted’, ‘sent’, ‘received’, ‘frozen’, ‘rejected’, ‘failed’, ‘dead’, ‘expired’.