ServiceUptime API Documentation

Introduction

Welcome to the ServiceUptime API documentation!

ServiceUptime provides industry standard REST+JSON API. Our API supports both HTTP GET/POST requests as well as JSON objects posted using HTTP POST. JSON is returned in all responses.

API Summary

API version

Vesion
1.0.1
Last modification
11/21/2014

API endpoint

The API endpont contains both autotization (i.e. API Key) and method information:

http://www.serviceuptime.com/api/{API_Key}/{API_Method}/

Also you can use secured version of API:

https://www.serviceuptime.com/api/{API_Key}/{API_Method}/

API Keys

Your API Keys are available on the API Keys page on Intercom, accessible from your settings. To create a Key, you can click the 'New API Key' button on that page. Since your API keys allow privileged access it is imperative you keep them secret. API Keys can be revoked via your settings in ServiceUptime.

Common Approaches

Data
API data is JSON encoded with UTF-8. API JSON is either a single object or a list of objects.
Authorization
Access control using API Keys.
Errors
4xx and 5xx responses returning JSON with error codes.
HTTP
Methods are used in accordance with HTTP GET or POST and resources are identified using URIs. All API requests can be sent over HTTPS as well.

Monitor Object

Common attributes

Attribute Type Description
Id Integer Monitor Id for your internal references (Read Only)
CheckPeriod Integer Monitor checks frequency in minutes. Possible values:
  • 1 - Every minute
  • 2 - Every 2 minutes
  • 3 - Every 3 minutes
  • 5 - Every 5 minutes
  • 10 - Every 10 minutes
  • 15 - Every 15 minutes
  • 30 - Every 30 minutes
  • 60 - Every hour
Timeout Integer Monitor timeout value in seconds. You will receive down alert if requers exeeds Timeout. Possible values: 5, 10, 15, 20, 25, 30, 35. This field will be ignored for ping ServiceType.
ServiceType String Monitored service type. Possible values: http, https, page, smtp, pop3, imap, ftp, ping, dns, mysql, link, dns lookup, tcp, ssl. You can find more info about ServiceType attribute here.
SendDefaultAlert Boolean Send email alert to Default Email Alert contact (can be set on the Profile section). Default value: y. Possible values:
  • y, 1, true - Enabled
  • n, 0, false - Disabled
SendAltAlert String List of email addresses those also should be alerted. Email addresses should be separated by semicolon ; or comma ,
FailuresBeforeAlert Integer Number of faile checks befure Email Alert. Possible values:
  • 1 - send email alert instantly after 1st failed check
  • 2 - send email alert after 2nd failed check
  • 3 - send email alert after 3rd failed check
  • 4 - send email alert after 4th failed check
  • 5 - send email alert after 5th failed check
SendDefaultSMS Boolean Send SMS alert to Default Mobile Phone number (can be set on the Profile section). Default value: n. Possible values:
  • y, 1, true - Enabled
  • n, 0, false - Disabled
SendAltSMS String List of phone number those also should be alerted. Numbers should contain country code (ex: +11234567890 for US numbers) and separated by semicolon ; or comma ,
FailuresBeforeSMS Integer Number of faile checks befure SMS Alert. Possible values:
  • 1 - send SMS alert instantly after 1st failed check
  • 2 - send SMS alert after 2nd failed check
  • 3 - send SMS alert after 3rd failed check
  • 4 - send SMS alert after 4th failed check
  • 5 - send SMS alert after 5th failed check
SendJabberAlert Boolean Send Jabber/XMPP alert to Default Jabber/XMPP contact (can be set on the Profile section). Default value: n. Possible values:
  • y, 1, true - Enabled
  • n, 0, false - Disabled
WebHookUrl String Webhook alert handler URL.
DownAlertSubject String The subject of 'DOWN' alerts message for email alerts, or content of 'DOWN' alert mesage for SMS alerts
UpAlertSubject String The subject of 'UP' alerts message for email alerts, or content of 'UP' alert mesage for SMS alerts
RepeatAlerts Integer Repeat DOWN alerts. Default value: 0. Possible values:
  • -1 - Send DOWN alert on every failed check
  • 0 - Do not repeat DOWN alerts
  • 30 - Repeat DOWN alerts every 30 minutes.
  • 60 - Repeat DOWN alerts every hour.
NoUpAlerts Boolean Do not send UP alerts. Default value: n. Possible values:
  • y, 1, true - Enabled
  • n, 0, false - Disabled
HighPriorityAlerts Boolean Send email alerts with High Priority flag. Default value: y. Possible values:
  • y, 1, true - Enabled
  • n, 0, false - Disabled
Enabled Boolean Whatever monitor is Active or not. Default value: y. Possible values:
  • y, 1, true - Enabled
  • n, 0, false - Disabled
PublicStatAllowed Boolean Allow public access to monitor statistics report. Default value: y. Possible values:
  • y, 1, true - Enabled
  • n, 0, false - Disabled
HostPage String This attribute will contain PageUrl for page and link monitors, and HostName for all other monitor types (Read Only)
Status String Monitor status as string. Possible values: active if monitor is active, or not_active if monitor is disabled or down if downtime is detected (Read Only)
StatusMessage String Monitor status message. Possible values: Monitor is UP, Monitor is DOWN or Monitor is INACTIVE (Read Only)
PubStatUrl String URI of public statistics report page (Read Only)
LastCheckDate Datetime Date and time of last monitor check in YYYY-MM-DD HH:mm:ss format (Read Only)
LastCheckDateFormatted String Formatted last check date and time. Example: 32 sec. ago (Read Only)
TotalChecks Integer Total number of performed checks (Read Only)
TotalOutages Integer Total number of detected outages (Read Only)
TotalFailedChecks Integer Total number of failed checks (Read Only)
TotalUptime Float Total uptime in percents (Read Only)

View raw JSON

web page monitor attributes

Attribute Type Description
PageUrl String Your web page URI. It can be regular (http://) or secured (https://) web page.
SearchTerm String String to search in web page HTML content. Note: we lookup only first 50Kb of web page code.
InverseSearch Boolean Allow to 'inverse' SearchTerm monitoring. I.e. ServiceUptime will alert you if found SearchTerm in your webpage content. Default value: n. Possible values:
  • y, 1, true - Enabled
  • n, 0, false - Disabled

View raw JSON

web page, http and https monitor attributes

Attribute Type Description
HTTPAuthLogin String Basic HTTP authorization username
HTTPAuthPassword String Basic HTTP authorization password

View raw JSON

dns lookup monitor attributes

Attribute Type Description
HostName String Domain name or host name or IP of name server to be monitored.
LookupDomain String Domain name to lookup in the name server provided in the HostName attribute
ExpectIp String Expected IP address. You will be alerted ServiceUptime resolve another IP address for your LookupDomain

View raw JSON

link monitor attributes

Attribute Type Description
PageUrl String Web page page URI where ServiceUptime should watch your back link. It can be regular (http://) or secured (https://) web page.
SearchLink String Back link URL (href attribute of A HTML tag)

View raw JSON

All other monitors except web page, dns lookup and link

Attribute Type Description
HostName String Domain name or host name or IP to be monitored.
Port Integer Monitored port. Default port will be used if empty. This field will be ignored for ping ServiceType.

View raw JSON

Supported Monitor Types

ServiceType Default Port Description
http tcp:80 Web-server (Apache, Microsoft IIS, NGNX, etc) monitoring
https ssl:443 Secure Web-server (Apache, Microsoft IIS, Nginx, etc) monitoring
page <empty> Web page content motitoring. Also useful for SOAP, ATOM, RSS, etc monitoring.
smtp tcp:25 Outgoing email server (Postfix, Courier, Sendmail, MS Exchange Server, etc)
pop3 tcp:110 Incomming email server (Qmail, Dovecot, MS Exchange Server, etc)
imap tcp:143 Incomming email server (Qmail, Dovecot, MS Exchange Server, etc)
ftp tcp:21 File transfer protocol server
ping <empty> PING service
dns udp:53 Name Server (BIND, PowerDNS, etc)
dns lookup udp:53 Name Server (BIND, PowerDNS, etc) will be looked up for your LookupDomain and returned IP address will be compared with your ExpectIp address
mysql tcp:3306 MySQL database server monitoring. Please do not forget to allow incomming connections from our check locations.
link <empty> The PageUrl content will be checked for your SearchLink back link. Useful for marketing links monitoring.
tcp tcp:8080 Custom TCP port monitoring
ssl ssl:995 Custom SSL port monitoring
tls tls:995 Custom TLS port monitoring

API Errors

Every API error will result 4xx or 5xx HTTP error code with error detailes in JSON object.

JSON Error Object

Attribute Value Description
status failed Request status
err_code Integer 4xx or 5xx error code
err_msg String Error description
data Object Error data (for example validation result for add-monitor or update-monitor requests)

Error Codes

Error Code Description
500 Wrong API Key
403 Your account is suspended
403 API is not available on free accounts
400 Wrong API Method
401 Access denied (API Key have no permission for requested action)
404 Monitor not found
500 API Error. Please try again later
520 Validation error (the data attribute will contain set of attributes with validation errors)

View raw JSON

API Response

Every successful API request will result '200 OK' HTTP code with response info as JSON object.

JSON Response Object

Attribute Value Description
status success Request status
err_code Integer 0
err_msg String <empty>
data Object Response data (for example monitor Id for add-monitor requests)

View raw JSON

API Methods

Method Description
add-monitor Add new monitor to your ServiceUptime account
update-monitor Edit monitor information
delete-monitor Remove monitor from your ServiceUptime account
get-monitors Retrieve all your monitors information including uptime statistics summary and current status info.
get-report Retrieve detailed uptime report for your monitor.
monitor-info Retrieve one monitor information including uptime statistics summary and current status info.
start-monitor Start monitoring for a paused monitor.
stop-monitor Pause monitoring for a monitor.
account-info Retrieve account information such as number of SMS credits, available monitors, default email alert, etc.

Add New Monitor

Method name: add-monitor

Method URI: http://www.serviceuptime.com/api/{API_Key}/add-monitor

This method creates new monitor under your ServiceUptime account

Request
Data Data Type Description
Monitor Object JSON or POST Monitor object should be sent to method URI by HTTP POST or as JSON request (JSON object in the HTTP POST request body)

View raw JSON/POST

Response
Data Data Type Description
Json Response Object JSON As result API will return JSON Response Object with created monitor Id on success, or JSON Error Object if request is failed. In case of validation error response will contain attributes validation errors in the data attribute of JSON Error Object.

View raw JSON

Edit Monitor

Method name: update-monitor

Method URI: http://www.serviceuptime.com/api/{API_Key}/update-monitor

This method updates existing monitor. The input Monitor Object can by reduced to field that you need to change, only Id attribute is mandatory. In this case all other attributes will not be updated.

Request
Data Data Type Description
Monitor Object JSON or POST Monitor object should be sent to method URI by HTTP POST or as JSON request (JSON object in the HTTP POST request body). Can be redused to changed attributes only.

View raw JSON/POST

Response
Data Data Type Description
Json Response Object JSON As result API will return JSON Response Object with updated monitor Id on success, or JSON Error Object if request is failed. In case of validation error response will contain attributes validation errors in the data attribute of JSON Error Object.

View raw JSON

Delete Monitor

Method name: delete-monitor

Method URI: http://www.serviceuptime.com/api/{API_Key}/delete-monitor

This method deletes existing monitor. The input Monitor Object must contain Id attribute.

Request
Data Data Type Description
Monitor Object JSON or POST The input Monitor Object must contain Id attribute.

View raw JSON/POST

Response
Data Data Type Description
Json Response Object JSON As result API will return JSON Response Object with updated monitor Id on success, or JSON Error Object if request is failed.

View raw JSON

Get All Monitors

Method name: get-monitors

Method URI: http://www.serviceuptime.com/api/{API_Key}/get-monitors

This method returnes all your moniotors as set of Monitor Objects in the data field of Response Object.

Request
Data Data Type Description
<empty> Empty request This method requires no input data.
Response
Data Data Type Description
Json Response Object JSON As result API will return JSON Response Object with set of Monitor Objects in the data attribute on success, or JSON Error Object if request is failed.

View raw JSON

Get Uptime Report

Method name: get-report

Method URI: http://www.serviceuptime.com/api/{API_Key}/get-report

This method returnes detailed uptime report for a monitor as JSON Object in the data field of Response Object.

Request
Data Data Type Description
Request Object JSON or POST The input Request Object must contain:
  • Id attribute set to Monitor Id
  • from_date Date in format YYYY-MM-DD
  • to_date Date in format YYYY-MM-DD

View raw JSON/POST

Response
Data Data Type Description
Json Response Object JSON As result API will return JSON Response Object with uptime report in the data attribute on success, or JSON Error Object if request is failed.

View raw JSON

Get Monitor Info

Method name: monitor-info

Method URI: http://www.serviceuptime.com/api/{API_Key}/monitor-info

Get info for a single monitor. The input Monitor Object must contain Id attribute.

Request
Data Data Type Description
Monitor Object JSON or POST The input Monitor Object must contain Id attribute.

View raw JSON/POST

Response
Data Data Type Description
Json Response Object JSON As result API will return JSON Monitor Object on success, or JSON Error Object if request is failed.

View raw JSON

Stop Monitor

Method name: stop-monitor

Method URI: http://www.serviceuptime.com/api/{API_Key}/stop-monitor

This method stops monitoring for a single monitor. The input Monitor Object must contain Id attribute.

Request
Data Data Type Description
Monitor Object JSON or POST The input Monitor Object must contain Id attribute.

View raw JSON/POST

Response
Data Data Type Description
Json Response Object JSON As result API will return JSON Response Object with stopped monitor Id on success, or JSON Error Object if request is failed.

View raw JSON

Start Monitor

Method name: start-monitor

Method URI: http://www.serviceuptime.com/api/{API_Key}/start-monitor

This method resumes monitoring for a stopped monitor. The input Monitor Object must contain Id attribute.

Request
Data Data Type Description
Monitor Object JSON or POST The input Monitor Object must contain Id attribute.

View raw JSON/POST

Response

As response this method returns JSON object with account information:

Data Data Type Description
Json Response Object JSON As result API will return JSON Response Object with resumed monitor Id on success, or JSON Error Object if request is failed.

View raw JSON

Get ServiceUptime Account Info

Method name: account-info

Method URI: http://www.serviceuptime.com/api/{API_Key}/account-info

This method return account information.

Request
Data Data Type Description
<empty> Empty request This method requires no input data.
Response

As response this method returns JSON Response Object with account information data in the data attribute:

Data Data Type Description
Json Response Object JSON As result API will return JSON Response Object with account info in the data attribute on success, or JSON Error Object if request is failed.
data attribute structure:
  • NumMonitors - Number of existing monitors
  • DefaultAlertEmail - Default email address for email alerts
  • DefaultPhoneNumber - Default phone number for SMS alerts
  • DefaultJabberAccount - Default Jabberaccount for XMPP alerts
  • SMSCredits - Number of available SMS credits
  • TimeZone - Account time zone
  • DaylightSaving - Whatever daylight saving is enabled for time zone (possible values: y or n)
  • Package - Account premuim package name
  • LastPaymentDate - Last payment date (in the format YYYY-MM-DD)
  • AvailableMonitors - Set of available check intervals and number of monitors available for every interval

View raw JSON

I myself have just signed up to your service as a friend of mine had passed me onto this service and since being with this service I have found it to be a great asset as it will help determine if my website is down as I host others website also. So thank you ServiceUptime for bringing us a great service.

Brian L.