NAV
shell

Introduction

Thank you for checking out Happy Apps. This page provides documentation for the full coverage Happy Apps API. It is an OAUTH 2.0 compatible REST API with support for manipulating almost all aspects of a users account. Create checks, groups, apps, get stats, incidents, settings, and even push check status updates for the PUSH based check type.

Authentication

The Happy Apps API follows the OAuth 2.0 Specification and acts as an OAUTH 2.0 provider. To authorize your account you will need to use the same credentials you normally use to login to happy apps which will provide you with an accessToken as well as a refreshToken

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl -X POST --data "username=meow&password=meow" "https://api.happyapps.io/oauth/token?grant_type=password&scope=write&client_id=ha-customer"

#Returns:
{
  "access_token": "d0cc2cc4-f7f5-4713-a874-34491e7707de",
  "expires_in": 31535996,
  "refresh_token": "cda88865-f88d-4ed9-a621-424d9361beb2",
  "scope": "write",
  "token_type": "bearer"
}

Make sure to replace meow with your username and password.

Happy apps expects all api requests to use the resultant access_token from the request made during authentication. This can be passed via the Authorization header. Be sure to replace the access_token with the actual token received from the OAuth request.

Authorization: BEARER access_token

Dashboard Stats

Ever wonder how to extract all those useful statistics from the dashboard? Happy Apps provides an API endpoint for fetching all your dashboard stats. This could come in handy if one wanted to integrate a Happy Apps dashboard into their own monitoring website or service.

Getting Dashboard Stats

curl "https://api.happyapps.io/api/dashboard"
  -H "Authorization: BEARER access_token"

Returns JSON of the following format

{
  "appList": [
    {
      "id": 1,
      "account": {
        "id": 1
      },
      "active": true,
      "allCheckStatus": null,
      "availability": 99.99282407,
      "checkGroups": [

      ],
      "checks": [
        {
          "id": 1
        }
      ],
      "createIncident": true,
      "dateCreated": "2015-01-27T01:28:56Z",
      "deleted": false,
      "description": null,
      "health": 10,
      "history": null,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "lastCheckStatus": null,
      "lastError": null,
      "lastErrorDate": null,
      "lastMessage": null,
      "lastRunDate": "2015-06-04T15:10:00Z",
      "lastSuccessDate": null,
      "lastTimer": 605,
      "lastUpdated": "2015-06-04T15:10:01Z",
      "lastWarningDate": null,
      "name": "My App",
      "severity": "critical",
      "urlName": null
    }
  ],
  "openIncidents": [

  ],
  "checkTypes": [
    {
      "id": 1,
      "code": "webGetCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "response",
      "name": "Web Check",
      "tunnelSupported": true
    },
    {
      "id": 2,
      "code": "mysqlCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "MySQL Check",
      "tunnelSupported": true
    },
    {
      "id": 3,
      "code": "mongoCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Mongo Check",
      "tunnelSupported": true
    },
    {
      "id": 4,
      "code": "elasticSearchCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "cluster status",
      "name": "Elastic Search Check",
      "tunnelSupported": true
    },
    {
      "id": 5,
      "code": "riakCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "write time",
      "name": "Riak Check",
      "tunnelSupported": true
    },
    {
      "id": 6,
      "code": "redisCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "key count",
      "name": "Redis Check",
      "tunnelSupported": true
    },
    {
      "id": 7,
      "code": "rabbitCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "queue count",
      "name": "Rabbit MQ Check",
      "tunnelSupported": true
    },
    {
      "id": 9,
      "code": "postgresCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Postgres Check",
      "tunnelSupported": true
    },
    {
      "id": 10,
      "code": "sqlCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Microsoft SQL Server",
      "tunnelSupported": true
    },
    {
      "id": 11,
      "code": "socketCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "response",
      "name": "Socket Check",
      "tunnelSupported": true
    },
    {
      "id": 12,
      "code": "pushCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Push API Check",
      "tunnelSupported": false
    },
    {
      "id": 13,
      "code": "pingCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Ping Check",
      "tunnelSupported": true
    }
  ],
  "history": [
    {
      "checkId": 215,
      "accountId": 1,
      "status": null,
      "lastTimer": 171,
      "lastErrorDate": "2015-05-18T09:24:00.000Z",
      "lastStats": null,
      "lastRunDate": "2015-06-04T15:10:00Z",
      "health": 10,
      "lastWarningDate": null,
      "inUptime": true,
      "createIncident": true,
      "lastCheckStatus": "success",
      "_id": "1433430600403215Aee7Ly9Qep",
      "lastBoxStats": null,
      "lastSuccessDate": "2015-06-04T15:10:00.169Z",
      "lastMetric": "200",
      "name": "MadTrack",
      "outageTime": 0,
      "lastMessage": "http 200",
      "checkTypeId": 1,
      "lastError": "http error: Read timed out",
      "internalError": false
    }
  ],
  "appStatus": {
    "avgHealth": 10,
    "avgResponseTime": 274,
    "warningApps": 0,
    "warningChecks": 0,
    "failApps": 0,
    "failChecks": 0,
    "successApps": 2,
    "mutedApps": 0,
    "successChecks": 8,
    "mutedChecks": 0,
    "allSuccess": true
  },
  "availability": 99.777486775714
}

This endpoint retrieves an overall appStatus with counts for the different states of your checks,groups, and apps. It also provides an account wide availability. Other features include recently run check history, a check list, and an app list for viewing.

HTTP Request

GET https://api.happyapps.io/api/dashboard

Checks

Checks are the basic entity of everything you do in Happy Apps. These entities define what and when a check is executed within the Happy Apps system. Happy Apps supports a vast array of different check types (not solely web checks). The API provides a means to list all of an account’s checks in addition to create, modify, mute, and or delete them.

Get All Checks

curl "https://api.happyapps.io/api/checks"
  -H "Authorization: BEARER access_token"

The above command returns JSON structured like this:

{
  "checks": [
    {
      "id": 798,
      "account": {
        "id": 1
      },
      "active": true,
      "availability": 99.9804109,
      "checkAgent": null,
      "checkIntegrations": [

      ],
      "checkInterval": 300,
      "checkSpec": null,
      "checkType": {
        "id": 1
      },
      "config": "{\n  \"webMethod\" : \"GET\",\n  \"webUrl\" : \"http:\\\/\\\/google.com\"\n}",
      "createIncident": true,
      "dateCreated": "2015-05-16T12:05:23Z",
      "deleted": false,
      "description": null,
      "health": 10,
      "history": "{\"checkDates\":[1433339580607,1433339595119,1433339613169,1433339625412,1433339641010,1433339655209,1433339670178,1433339687802,1433339700471,1433339715171,1433339730710,1433339745351,1433339764299,1433339775508,1433339790377,1433339805373,1433339820944,1433339835996,1433339850317,1433339865833,1433339880884,1433339895489,1433339910554,1433339925660,1433339940875,1433339956143,1433339970551,1433339985179,1433340000961,1433340015765],\"successList\":[true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true],\"healthList\":[10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10],\"timerList\":[347,410,338,337,365,361,373,374,358,337,350,505,342,338,358,359,381,354,353,377,342,344,349,363,329,352,350,348,356,345]}",
      "inUptime": true,
      "lastBoxStats": null,
      "lastCheckStatus": "success",
      "lastError": "http error: Read timed out",
      "lastErrorDate": "2015-05-18T09:25:15Z",
      "lastMessage": "http 200",
      "lastMetric": "200",
      "lastRunDate": "2015-06-03T14:00:16Z",
      "lastStats": null,
      "lastSuccessDate": "2015-06-03T14:00:16Z",
      "lastTimer": 345,
      "lastUpdated": "2015-06-03T14:00:16Z",
      "lastWarningDate": null,
      "name": "Purity Plus",
      "nextRunDate": "2015-06-03T14:00:16Z",
      "severity": "critical",
      "startDate": null
    }
  ]
}

This endpoint retrieves all checks and their JSON encoded configuration attributes based on check type. Check data is encrypted in the database.

HTTP Request

GET https://api.happyapps.io/api/checks

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
lastUpdated null Date filter, restricts query to only load checks updated timestamp is more recent or equal to the date specified
deleted undefined Used to specify you can load previously deleted checks. Useful for synchronizing deleted records in your client side store.

Get a Specific Check

curl "https://api.happyapps.io/api/checks/1" \
  -H "Authorization: BEARER access_token"

The above command returns JSON structured like this:

{
  "success": true,
  "check:" {
    "id": 798,
    "account": {
      "id": 1
    },
    "active": true,
    "availability": 99.9804109,
    "checkAgent": null,
    "checkIntegrations": [

    ],
    "checkInterval": 300,
    "checkSpec": null,
    "checkType": {
      "id": 1
    },
    "config": "{\n  \"webMethod\" : \"GET\",\n  \"webUrl\" : \"http:\\\/\\\/google.com\"\n}",
    "createIncident": true,
    "dateCreated": "2015-05-16T12:05:23Z",
    "deleted": false,
    "description": null,
    "health": 10,
    "history": "{\"checkDates\":[1433339580607,1433339595119,1433339613169,1433339625412,1433339641010,1433339655209,1433339670178,1433339687802,1433339700471,1433339715171,1433339730710,1433339745351,1433339764299,1433339775508,1433339790377,1433339805373,1433339820944,1433339835996,1433339850317,1433339865833,1433339880884,1433339895489,1433339910554,1433339925660,1433339940875,1433339956143,1433339970551,1433339985179,1433340000961,1433340015765],\"successList\":[true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true],\"healthList\":[10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10],\"timerList\":[347,410,338,337,365,361,373,374,358,337,350,505,342,338,358,359,381,354,353,377,342,344,349,363,329,352,350,348,356,345]}",
    "inUptime": true,
    "lastBoxStats": null,
    "lastCheckStatus": "success",
    "lastError": "http error: Read timed out",
    "lastErrorDate": "2015-05-18T09:25:15Z",
    "lastMessage": "http 200",
    "lastMetric": "200",
    "lastRunDate": "2015-06-03T14:00:16Z",
    "lastStats": null,
    "lastSuccessDate": "2015-06-03T14:00:16Z",
    "lastTimer": 345,
    "lastUpdated": "2015-06-03T14:00:16Z",
    "lastWarningDate": null,
    "name": "Purity Plus",
    "nextRunDate": "2015-06-03T14:00:16Z",
    "severity": "critical",
  }
}

This endpoint retrieves a specific check.

HTTP Request

GET https://api.happyapps.io/api/checks/:id

URL Parameters

Parameter Description
ID ID of the check to retrieve

Create a Check

curl -XPOST "https://api.happyapps.io/api/checks" \
  -H "Authorization: BEARER access_token" \
  -H "Content-Type: application/json" \
  -d '{"check":{
    "name": "My Check",
    "checkType": {"code": "webGetCheck"},
    "inUptime": true,
    "severity": "critical",
    "description": null,
    "checkInterval": 300,
    "checkAgent": null,
    "active": true,
    "config": "{\n  \"webMethod\" : \"GET\",\n  \"webUrl\" : \"http:\\\/\\\/google.com\"\n}",
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single check

HTTP Request

POST https://api.happyapps.io/api/checks

JSON Check Parameters

Parameter Default Description
name null Unique name scoped to your account for the check
description null Optional description field
checkType null Check type you want to create, use code and a valid check type: {"code": "webGetCheck"}
checkInterval 300 Number of seconds you want between check executions (minimum value is 60, depending on your subscription plan)
inUptime true Used to determine if check should affect account wide availability calculations
active true Used to determine if check should be scheduled to execute
severity critical Severity level of incidents that are created when this check fails. They can be info, warning, or critical
checkAgent null Specifies agent you want to run the check with i.e. {"id": 1} See Agents for more information
config null JSON encoded list of parameters that varies by check type. See below for more information

Updating a Check

curl -XPUT "https://api.happyapps.io/api/checks/1" \
  -H "Authorization: BEARER access_token" \
  -H "Content-Type: application/json" \
  -d '{"check":{
    "name": "My Check",
    "checkType": {"code": "webGetCheck"},
    "inUptime": true,
    "severity": "critical",
    "description": null,
    "checkInterval": 300,
    "checkAgent": null,
    "active": true,
    "config": "{\n  \"webMethod\" : \"GET\",\n  \"webUrl\" : \"http:\\\/\\\/google.com\"\n}",
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single check

HTTP Request

PUT https://api.happyapps.io/api/checks/:id

JSON Check Parameters

Parameter Default Description
name null Unique name scoped to your account for the check
description null Optional description field
checkType null Check type you want to create, use code and a valid check type: {"code": "webGetCheck"}
checkInterval 300 Number of seconds you want between check executions (minimum value is 60, depending on your subscription plan)
inUptime true Used to determine if check should affect account wide availability calculations
active true Used to determine if check should be scheduled to execute
severity critical Severity level of incidents that are created when this check fails. They can be info, warning, or critical
checkAgent null Specifies agent you want to run the check with i.e. {"id": 1} See Agents for more information
config null JSON encoded list of parameters that varies by check type. See below for more information

Check Types and Options

We support a wide variety of check types. Each check type varies in its configuration payload when determining how the check should be run.

Creates a Web type Check

Web Get Check

{
  "check": {
    "name": "My Web Check",
    "checkType": {"code": "webGetCheck"},
    "config": "{\"webMethod\":\"GET\",\"webUrl\": \"http:\\\/\\\/google.com\", \"checkUser\":\"basicUser\",\"checkPassword\":\"basicPassword\", \"webTextMatch\": \"Login\", \"textCheckOn\": \"on\"}"
  }
}

Code: webGetCheck

Web check type allows you to perform a standard web request and validate the response came back successfully. Additionally, you can check for matching text within the result. There are several config parameters available for use with this type of check

Parameter Requirement Description
webMethod Yes HTTP method to use for testing (GET or POST)
webUrl Yes Web URL you wish to use to run a check on
checkUser No If you want to use HTTP Basic Authentication, populate this field with the username
checkPassword No If you want to use HTTP basic Authentication, populate this field with the password
textCheckOn No Set value to “on” if you want to turn on text matching
webTextMatch No Set the string you want to look for in the page source

MySQL Check

{
  "check": {
    "name": "MySql Check",
    "checkType": {"code": "mysqlCheck"},
    "config": "{\"dbHost\":\"db.example.org\",\"dbPort\": \"3306\", \"dbUser\":\"basicUser\",\"dbPassword\":\"basicPassword\", \"dbName\": \"mydb\", \"dbQuery\": \"select 1\", \"checkOperator\": \"lt\", \"checkResult\": 2}"
  }
}

Code: mysqlCheck

MySQL check allows you to execute a query so that you may validate the value returned in addition to verifying the database is responding. This can be useful for doing a slow query check or just making sure something isn’t growing out of control.

Parameter Requirement Description
dbHost Yes Hostname or IP address of the MySQL database
dbPort Yes MySQL Port (defaults to 3306)
dbUser Yes Database username
dbPassword Yes Database password, (all check data is encrypted inside the Happy Apps database)
dbName Yes Database name you would like to connect to
checkOperator No Can be set to lt (less than), gt (greater than), equal (Equal to) for comparison
checkResult No Numerical value to compare the check result against

SQL Server Check

{
  "check": {
    "name": "SQL Server Check",
    "checkType": {"code": "sqlCheck"},
    "config": "{\"dbHost\":\"db.example.org\",\"dbPort\": \"3306\", \"dbUser\":\"basicUser\",\"dbPassword\":\"basicPassword\", \"dbName\": \"mydb\", \"dbQuery\": \"select 1\", \"checkOperator\": \"lt\", \"checkResult\": 2}"
  }
}

Code: sqlCheck

SQL Server check allows to execute a query so that you may validate the value returned in addition to verifying the database is responding. This can be useful for doing a slow query check or just making sure something isn’t growing out of control.

Parameter Requirement Description
dbHost Yes Hostname or IP address of the SQL database
dbPort Yes SQL Port (defaults to 1433)
dbUser Yes Database username
dbPassword Yes Database password, (all check data is encrypted inside the Happy Apps database)
dbName Yes Database name you would like to connect to
checkOperator No Can be set to lt (less than), gt (greater than), equal (Equal to) for comparison
checkResult No Numerical value to compare the check result against

PostgreSQL Check

{
  "check": {
    "name": "PostgerSQL Check",
    "checkType": {"code": "postgresCheck"},
    "config": "{\"dbHost\":\"db.example.org\",\"dbPort\": \"3306\", \"dbUser\":\"basicUser\",\"dbPassword\":\"basicPassword\", \"dbName\": \"mydb\", \"dbQuery\": \"select 1\", \"checkOperator\": \"lt\", \"checkResult\": 2}"
  }
}

Code: postgresCheck

PostgreSQL check allows to execute a query so that you may validate the value returned in addition to verifying the database is responding. This can be useful for doing a slow query check or just making sure something isn’t growing out of control.

Parameter Requirement Description
dbHost Yes Hostname or IP address of the PostgreSQL database
dbPort Yes SQL Port (defaults to 5432)
dbUser Yes Database username
dbPassword Yes Database password, (all check data is encrypted inside the Happy Apps database)
dbName Yes Database name you would like to connect to
checkOperator No Can be set to lt (less than), gt (greater than), equal (Equal to) for comparison
checkResult No Numerical value to compare the check result against

Socket Check

{
  "check": {
    "name": "Socket Check",
    "checkType": {"code": "socketCheck"},
    "config": "{\"host\":\"test.example.org\",\"port\": \"3306\", \"send\":\"blah\",\"responseMatch\":\"OK\"}"
  }
}

Code: socketCheck

Socket check confirms a certain TCP port is up and responding in your environment. It can be configured do an initial send upon connect and compare and expected response of the service.

Parameter Requirement Description
host Yes Hostname or IP address of the socket server
port Yes TCP port
send No Connection string you might want to send to the service
responseMatch No Response from the service to match against

Elastic Search Check

{
  "check": {
    "name": "Socket Check",
    "checkType": {"code": "elasticSearchCheck"},
    "config": "{\"esHost\":\"test.example.org\",\"esPort\": \"9200\"}"
  }
}

Code: elasticSearchCheck

Elasticsearch check is capable of connecting to your Elasticsearch, cluster or node, verifying its health. In addition, Happy Apps will also pull statistical information such as: document size, capacity, and cpu usage.

Parameter Requirement Description
esHost Yes Hostname or IP address of the Elasticsearch server
esPort Yes Port to connect to the HTTP service

Push Check

{
  "check": {
    "name": "Push Check",
    "checkType": {"code": "pushCheck"}
  }
}

Code: pushCheck

A Push check is a check that is updated by a web hook. An external source is responsible for periodically submitting a check status. Please see the section on Push Checks API for details.

SSH Tunneling

SSH tunneling options allow the different check types to tunnel to a host via a proxy, and execute checks relative to the proxy. A SSH tunnel can use your account generated public and private key-pairs or SSH password (we strongly recommend using a key-pair).

To enable SSH tunneling for a check, add the following parameters to any check type config as seen earlier in the Check Types section.

{
  "check": {
    "name": "Socket Check",
    "checkType": {"code": "elasticSearchCheck"},
    "config": "{\"esHost\":\"test.example.org\",\"esPort\": \"9200\", \"tunnelOn\": \"on\", \"sshHost\": \"example.org\", \"sshPort\": 22, \"sshUser\": \"happyapps\"}"
  }
}
Parameter Requirement Description
tunnelOn Yes Set to on to turn on tunneling
sshHost Yes Hostname or IP address of the proxy host
sshPort No Port for SSH on the proxy host, defaults to 22
sshUser Yes SSH user on the proxy host to login as
sshPassword No Password for user, if not using key based authentication

Mute a Check

curl -XPUT "https://api.happyapps.io/api/checks/1/mute" \
  -H "Authorization: BEARER access_token" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

The above command returns JSON structure like this:

{
  "muteState": "QUARANTINED",
  "success": true
}

This endpoint can be used to toggle the mute state of a check on and off.

HTTP Request

PUT https://api.happyapps.io/api/checks/:id/mute

JSON Parameters

Parameter Description
enabled Set to true or false

Delete a Check

curl -XDELETE "https://api.happyapps.io/api/checks/1" \
  -H "Authorization: BEARER access_token"

The above command returns JSON structure like this:

{
  "success": true
}

A deleted check can be fetched from the API using the GET method to synchronize client side views, but can not be executed or updated.

Push Checks

A Push Check is a check type that is not run by any of our happy apps check servers nor an agent. Rather it acts as a web hook where the user is responsible for submitting status updates to happy apps about the check. These status updates need to be regularly submitted and consistent with the checks configured time interval. If a check has not been heard from for more than 2x the check interval time it is marked as a failed check and an incident is raised.

To create a Push Check please check the Checks API or create a Push Check in the UI.

Submitting a Check Status

curl -XPOST https://api.happyapps.io/api/push?apiKey=INSERT_KEY_HERE -H 'Content-Type: application/json' \
--data '{
  "success":true,
  "message": "any comment goes here",
  "startDate": "2015-05-01T12:35:14Z",
  "endDate": "2015-05-01T12:35:14Z"
  }'

The above will return JSON in the format of

{"success":true}

If you are pushing updates to quickly the response will be a 429 with the following payload

{"success":false,"msg":"Pushed too quickly, please wait 54004ms before sending again."}

HTTP Request

POST https://api.happyapps.io/api/push?apiKey=INSERT_KEY_HERE

JSON Parameters

Parameter Default Description
success false Set wether or not the check passed
startDate NOW() The start time of the check run (optional)
endDate NOW() The end time of the check run time (if specified with start date the response time metric will be accurately represented)
message null An optional string message that will show in the check history for the particular check run

Check Types

A set of APIs for fetching a list of available check types is also provided. This API can make it useful for associating a check type code to an ID for check GET and POST requests.

Get All Check Types

curl "https://api.happyapps.io/api/check-types"
  -H "Authorization: BEARER access_token"

The above command returns JSON structured like this

{
  "checkTypes": [
    {
      "id": 1,
      "code": "webGetCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "response",
      "name": "Web Check",
      "tunnelSupported": true
    },
    {
      "id": 2,
      "code": "mysqlCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "MySQL Check",
      "tunnelSupported": true
    },
    {
      "id": 3,
      "code": "mongoCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Mongo Check",
      "tunnelSupported": true
    },
    {
      "id": 4,
      "code": "elasticSearchCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "cluster status",
      "name": "Elastic Search Check",
      "tunnelSupported": true
    },
    {
      "id": 5,
      "code": "riakCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "write time",
      "name": "Riak Check",
      "tunnelSupported": true
    },
    {
      "id": 6,
      "code": "redisCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "key count",
      "name": "Redis Check",
      "tunnelSupported": true
    },
    {
      "id": 7,
      "code": "rabbitCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "queue count",
      "name": "Rabbit MQ Check",
      "tunnelSupported": true
    },
    {
      "id": 9,
      "code": "postgresCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Postgres Check",
      "tunnelSupported": true
    },
    {
      "id": 10,
      "code": "sqlCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Microsoft SQL Server",
      "tunnelSupported": true
    },
    {
      "id": 11,
      "code": "socketCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "response",
      "name": "Socket Check",
      "tunnelSupported": true
    },
    {
      "id": 12,
      "code": "pushCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Push API Check",
      "tunnelSupported": false
    },
    {
      "id": 13,
      "code": "pingCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Ping Check",
      "tunnelSupported": true
    }
  ]
}

HTTP Request

GET https://api.happyapps.io/api/check-types

Get Specific Check Type

curl "https://api.happyapps.io/api/check-types/10"
  -H "Authorization: BEARER access_token"

The above command returns JSON structured like this

{
  "success": true,
  "checkType": {
    "id": 10,
    "code": "sqlCheck",
    "createIncident": true,
    "defaultInterval": 300000,
    "iconPath": null,
    "iconType": "upload",
    "inUptime": true,
    "metricName": "result",
    "name": "Microsoft SQL Server",
    "tunnelSupported": true
  }
}

HTTP Request

GET https://api.happyapps.io/api/check-types/1

Groups

Groups are a useful means to organize a set of checks. An example might be 3 web servers grouped under a web balancer. Or 2 mysql servers tied together as masters. This can be useful in setting up a hierarchy of the application infrastructure and help to properly create an availability discernment for you and your customers.

Get All Groups

curl "https://api.happyapps.io/api/groups"
  -H "Authorization: BEARER access_token"

The above command returns JSON structured like this:

{
  "checkGroups": [
    {
      "id": 1,
      "account": {
        "id": 1
      },
      "availability": 99.87202932,
      "checks": [
        {
          "id": 3
        }
      ],
      "createIncident": true,
      "dateCreated": "2015-01-26T18:43:01Z",
      "deleted": false,
      "description": null,
      "health": 10,
      "history": null,
      "inUptime": true,
      "lastCheckStatus": null,
      "lastError": null,
      "lastErrorDate": null,
      "lastMessage": null,
      "lastMetric": null,
      "lastRunDate": "2015-05-16T14:14:15Z",
      "lastSuccessDate": null,
      "lastTimer": 246,
      "lastUpdated": "2015-05-16T14:14:15Z",
      "lastWarningDate": null,
      "minHappy": 1,
      "name": "My Group",
      "outageTime": 0,
      "severity": "critical"
    }
  ]  
}

This endpoint retrieves all groups and a list of checks associated with the group by id.

HTTP Request

GET https://api.happyapps.io/api/groups

Query Parameters

Parameter Default Description
max 25 The max number of results to return
offset 0 The offset of records you want to load
lastUpdated null A date filter, restricts query to only load groups updated more recent or equal to the date specified
deleted undefined if this param is specified you can load previously deleted checks. This is useful for synchronizing deleted records in your client side store.

Get a Specific Group

curl "https://api.happyapps.io/api/groups/1" \
  -H "Authorization: BEARER access_token"

The above command returns JSON structured like this:

{
  "success": true,
  "checkGroup": {
    "id": 1,
    "account": {
      "id": 1
    },
    "availability": 99.87202932,
    "checks": [
      {
        "id": 3
      }
    ],
    "createIncident": true,
    "dateCreated": "2015-01-26T18:43:01Z",
    "deleted": false,
    "description": null,
    "health": 10,
    "history": null,
    "inUptime": true,
    "lastCheckStatus": null,
    "lastError": null,
    "lastErrorDate": null,
    "lastMessage": null,
    "lastMetric": null,
    "lastRunDate": "2015-05-16T14:14:15Z",
    "lastSuccessDate": null,
    "lastTimer": 246,
    "lastUpdated": "2015-05-16T14:14:15Z",
    "lastWarningDate": null,
    "minHappy": 1,
    "name": "My Group",
    "outageTime": 0,
    "severity": "critical"
  }
}

This endpoint retrieves a specific group.

HTTP Request

GET https://api.happyapps.io/api/groups/:id

URL Parameters

Parameter Description
ID The ID of the group to retrieve

Create a Group

curl -XPOST "https://api.happyapps.io/api/groups" \
  -H "Authorization: BEARER access_token" \
  -H "Content-Type: application/json" \
  -d '{"checkGoup":{
    "name": "My Group",
    "inUptime": true,
    "severity": "critical",
    "description": null,
    "happyAppCheckIds": [1,2,3]
  }}'

The above command returns JSON structured like getting a single group:

HTTP Request

POST https://api.happyapps.io/api/groups

JSON Check Parameters

Parameter Default Description
name null A unique name scoped to your account for the group
description null Optional description field if you want to put more info there
inUptime true Wether or not this group should affect account wide availability calculations.
severity critical The severity level of incidents that are created when this group fails. They can be one of info, warning, or critical
happyAppCheckIds null Array of check ids to be placed within the group

Updating a Group

curl -XPUT "https://api.happyapps.io/api/groups/1" \
  -H "Authorization: BEARER access_token" \
  -H "Content-Type: application/json" \
  -d '{"checkGroup":{
    "name": "My Group",
    "inUptime": true,
    "severity": "critical",
    "description": null,
    "happyAppCheckIds": [1,2,3]
  }}'

The above command returns JSON structured like getting a single group:

HTTP Request

PUT https://api.happyapps.io/api/groups/:id

JSON Check Parameters

Parameter Default Description
name null A unique name scoped to your account for the group
description null Optional description field if you want to put more info there
inUptime true Wether or not this group should affect account wide availability calculations.
severity critical The severity level of incidents that are created when this group fails. They can be one of info, warning, or critical
happyAppCheckIds null Array of check ids to be placed within the group

Mute a Group

curl -XPUT "https://api.happyapps.io/api/groups/1/mute" \
  -H "Authorization: BEARER access_token" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

The above command returns JSON structured like this:

{
  "muteState": "QUARANTINED",
  "success": true
}

This endpoint can be used to toggle the mute state of a Group.

HTTP Request

PUT https://api.happyapps.io/api/groups/:id/mute

JSON Parameters

Parameter Description
enabled Set this to true or false depending on if you want to mute or unmute a group.

Delete a Group

curl -XDELETE "https://api.happyapps.io/api/groups/1" \
  -H "Authorization: BEARER access_token"

The above command returns JSON Structured like this:

{
  "success": true
}

A Deleted group can be fetched optionally from the GET api for sync verification but can no longer be used or updated.

Apps

Apps are a useful means to organize a set of checks and groups. You can assign any set of checks or groups to an app to define what items in your infrastructure affect an overall applications health. This is useful for scoping incidents to the engineering team responsible for an application and also to provide an overview of what a check failure might actually be affecting throughout your environment.

Get All Apps

curl "https://api.happyapps.io/api/apps"
  -H "Authorization: BEARER access_token"

The above command returns JSON structured like this:

{
  "apps": [
    {
      "id": 2,
      "account": {
        "id": 1
      },
      "active": true,
      "allCheckStatus": null,
      "availability": null,
      "checkGroups": [

      ],
      "checks": [

      ],
      "createIncident": true,
      "dateCreated": "2015-02-09T21:14:51Z",
      "deleted": false,
      "description": null,
      "health": 9,
      "history": null,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "lastCheckStatus": null,
      "lastError": null,
      "lastErrorDate": null,
      "lastMessage": null,
      "lastRunDate": null,
      "lastSuccessDate": null,
      "lastTimer": 0,
      "lastUpdated": "2015-02-09T21:14:51Z",
      "lastWarningDate": null,
      "name": "My blank app",
      "severity": "critical",
      "urlName": null
    }
  ],
  "appCount": 1
}

This endpoint retrieves all apps and a list of checks and groups associated with the app by id.

HTTP Request

GET https://api.happyapps.io/api/apps

Query Parameters

Parameter Default Description
max 25 The max number of results to return
offset 0 The offset of records you want to load
lastUpdated null A date filter, restricts query to only load apps updated more recent or equal to the date specified
deleted undefined if this param is specified you can load previously deleted apps. This is useful for synchronizing deleted records in your client side store.

Get a Specific App

curl "https://api.happyapps.io/api/apps/1" \
  -H "Authorization: BEARER access_token"

The above command returns JSON structured like this:

{
  "success": true,
  "app": {
    "id": 2,
    "account": {
      "id": 1
    },
    "active": true,
    "allCheckStatus": null,
    "availability": null,
    "checkGroups": [

    ],
    "checks": [

    ],
    "createIncident": true,
    "dateCreated": "2015-02-09T21:14:51Z",
    "deleted": false,
    "description": null,
    "health": 9,
    "history": null,
    "iconPath": null,
    "iconType": "upload",
    "inUptime": true,
    "lastCheckStatus": null,
    "lastError": null,
    "lastErrorDate": null,
    "lastMessage": null,
    "lastRunDate": null,
    "lastSuccessDate": null,
    "lastTimer": 0,
    "lastUpdated": "2015-02-09T21:14:51Z",
    "lastWarningDate": null,
    "name": "My blank app",
    "severity": "critical",
    "urlName": null
  }
}

This endpoint retrieves a specific app.

HTTP Request

GET https://api.happyapps.io/api/apps/:id

URL Parameters

Parameter Description
ID The ID of the app to retrieve

Create a App

curl -XPOST "https://api.happyapps.io/api/apps" \
  -H "Authorization: BEARER access_token" \
  -H "Content-Type: application/json" \
  -d '{"app":{
    "name": "My App",
    "inUptime": true,
    "severity": "critical",
    "description": null,
    "happyAppCheckIds": [1,2,3],
    "happyAppCheckGroupIds": [1,2,3]
  }}'

The above command returns JSON structured like getting a single app:

HTTP Request

POST https://api.happyapps.io/api/apps

JSON Check Parameters

Parameter Default Description
name null A unique name scoped to your account for the app
description null Optional description field if you want to put more info there
inUptime true Wether or not this app should affect account wide availability calculations.
severity critical The severity level of incidents that are created when this app fails. They can be one of info, warning, or critical
happyAppCheckIds null Array of check ids to be placed within the app
happyAppCheckGroupIds null Array of group ids to be placed within the app

Updating a App

curl -XPUT "https://api.happyapps.io/api/apps/1" \
  -H "Authorization: BEARER access_token" \
  -H "Content-Type: application/json" \
  -d '{"app":{
    "name": "My App",
    "inUptime": true,
    "severity": "critical",
    "description": null,
    "happyAppCheckIds": [1,2,3],
    "happyAppCheckGroupIds": [1,2,3]
  }}'

The above command returns JSON structured like getting a single app:

HTTP Request

PUT https://api.happyapps.io/api/apps/:id

JSON Check Parameters

Parameter Default Description
name null A unique name scoped to your account for the app
description null Optional description field if you want to put more info there
inUptime true Wether or not this app should affect account wide availability calculations.
severity critical The severity level of incidents that are created when this app fails. They can be one of info, warning, or critical
happyAppCheckIds null Array of check ids to be placed within the app
happyAppCheckGroupIds null Array of group ids to be placed within the app

Mute a App

curl -XPUT "https://api.happyapps.io/api/apps/1/mute" \
  -H "Authorization: BEARER access_token" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

The above command returns JSON structured like this:

{
  "muteState": "QUARANTINED",
  "success": true
}

This endpoint can be used to toggle the mute state of a App.

HTTP Request

PUT https://api.happyapps.io/api/apps/:id/mute

JSON Parameters

Parameter Description
enabled Set this to true or false depending on if you want to mute or unmute a app.

Delete a App

curl -XDELETE "https://api.happyapps.io/api/apps/1" \
  -H "Authorization: BEARER access_token"

The above command returns JSON Structured like this:

{
  "success": true
}

A Deleted app can be fetched optionally from the GET api for sync verification but can no longer be used or updated.

Incidents

Incidents are used to keep track of failed checks, groups, and apps. They can be used to keep a running history of what failed and when. They can also be updated to provide notes and resolution information. An incident can also be scoped to an app, many checks, or many groups depending on your defined heirarchy.

Get All Incidents

curl "https://api.happyapps.io/api/incidents"
  -H "Authorization: BEARER access_token"

The above command returns JSON structured like this:

{
  "openIncidents": [

  ],
  "incidentStats": {
    "today": 0,
    "week": 0,
    "month": 32
  },
  "incidents": [
    {
      "id": 122,
      "account": {
        "id": 1
      },
      "app": null,
      "autoClose": true,
      "autoManaged": true,
      "channelId": "f8d47f3e-1bbb-4b7e-9e53-8c396acc6e86",
      "checkGroups": [

      ],
      "checks": [
        {
          "id": 1
        }
      ],
      "comment": null,
      "dateCreated": "2015-05-31T19:57:29Z",
      "duration": 65286,
      "endDate": "2015-05-14T21:12:45Z",
      "inUptime": true,
      "incidentEvents": [
        {
          "id": 268
        },
        {
          "id": 267
        }
      ],
      "lastCheckTime": "2015-05-14T21:11:40Z",
      "lastError": "http error: www.googleFAILNOW.com: nodename nor servname provided, or not known",
      "lastMessage": null,
      "lastUpdated": "2015-05-31T19:57:41Z",
      "name": null,
      "notificationEvents": [
        {
          "id": 196
        },
        {
          "id": 195
        }
      ],
      "resolution": null,
      "severity": "critical",
      "severityId": 20,
      "startDate": "2015-05-14T21:11:40Z",
      "status": "closed",
      "visibility": "private"
    }
  ],
  "incidentCount": 109

This endpoint retrieves all open incidents, a pageable list of all incidents, and a stat summary of incidents

HTTP Request

GET https://api.happyapps.io/api/incidents

Query Parameters

Parameter Default Description
max 25 The max number of results to return
offset 0 The offset of records you want to load
lastUpdated null A date filter, restricts query to only load incidents updated more recent or equal to the date specified

Errors

The Happy Apps API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The entity requested is restricted
404 Not Found – The specified kitten could not be found
405 Method Not Allowed – You tried to access an entity with an invalid method
406 Not Acceptable – You requested a format that isn’t json
429 Too Many Requests – You’re requesting too many entities! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.