API Version 1

Authentication

Authentication is performed with Basic HTTP Authentication over HTTPS by providing a Knowledge Front account and password credentials.

Example using curl from the command line:

curl --user email@example.com:password https://api.knowledgefront.com/v1/Status/

See Managing Users for information on creating and managing user accounts.

Alert Status Summary

Get Alert Status List

URL: https://api.knowledgefront.com/v1/Status/
Description: Quick summary of alert status by monitor. A global_alert_active boolean is also given as a shortcut to iterating over the entire list and provides a simple way to determine if any alerts have been triggered.
Note: Pausing alerts has an impact on this API call. If a monitor’s alerts are paused the alert_active will report false
HTTP Method: GET
Parameters: None

Response

Attribute	Type	Description
path	string	the current request path /v1/Status/
global_alert_active	boolean	true if any monitor’s alert is active
monitor_list	array	List of monitor objects
monitor_list[INDEX].alert_active	boolean	true if at least one this monitor’s alert is active and not reset
monitor_list[INDEX].id	string	unique identifier for the monitor
monitor_list[INDEX].label	string	The user defined label for the monitor
monitor_list[INDEX].type	string	Monitor type. May be one of DNS Query, HTTP, TCP Port, Ping, SSH Port, SMTP

Sample Request

curl --user email@example.com:password https://api.knowledgefront.com/v1/Status/

Sample Output

{
        "error": null,
        "global_alert_active": false,
        "monitor_list": [
                {
                        "alert_active": false,
                        "id": "2cdb022f27777777ae4ca7f1d08fcff78b539e2011e2f2ab69d891ba",
                        "label": "Web Test",
                        "type": "HTTP"

                },
                {
                        "alert_active": false,
                        "id": "0fd7e5777777720832fa984495aa373d10437ec0c270d521c245e02c",
                        "label": "MX Failover",
                        "type": "SMTP"

                },
                {
                        "alert_active": false,
                        "id": "8596111c13beb595864289777777736b67cc86d3b8bbef2b6910bc0b",
                        "label": "MX Primary",
                        "type": "SMTP"

                },
                {
                        "alert_active": false,
                        "id": "ff781cd47f5434fabd748495074147777777759cbccebce71ab371a1",
                        "label": "MX Lookup",
                        "type": "DNS Query"

                }
        ],
        "path": "/v1/Status/"
}

back to contents

Status Filter Summary

Request

URL: https://api.knowledgefront.com/v1/Status/Filter/
Description: The filtered summary has a few query parameters to limit the list of monitors. Status information returned includes a few more details about the most recent test and alerts. Parameters suffix, prefix, contains can be combined to help narrow monitor results.
HTTP Method: GET

Parameters

Attribute	Type	Description	Required
t	integer	Time in seconds from now. Contrains the query to the previous t seconds. Defaults to 1800	no
prefix	string	Filter status report to include monitors based with labels beginning with prefix	no - but one or more of prefix, suffix, meta, and/or contains must be specified
suffix	string	Filter based on monitor labels ending with suffix	no
contains	string	Filter based on monitor labels containing the string given	no
meta	string	Filter based on monitor meta data in the form of key:value or key:value,key:value	no

Response

Attribute	Type	Description
path	string	/v1/Status/Filter/
error	string	Any error returned by the server. null if none
t	integer	Echo of the t parameter given, or used, in the query
monitor_list	array	List of monitor status objects
monitor_list[INDEX]	object	Single monitor status. See Single Monitor Status response below

Status Filter Response Attributes

Attribute	Type	Description
alert_active	bool	True if an alert is currently active
alert_count	integer	Number of alerts triggered during the query period
fail_count	integer	Number of tests that have not been completed
label	string	Monitor name/label
last_alert	object	The most recent alert to have triggered. See Alert object below
last_failed	object	Most recent test failure data point. See Data object below
last_test	object	Data from most recent test. See Data object below
monitor	string	Unique ID of monitor
test_count	integer	Number of tests for the given time period

Status Filter Response - Single Monitor Status

Attribute	Type	Description
duration	integer	Represents the response time of the test. In the case of SMTP monitors it is the total round trip time in seconds
error	string	Error message. Null if none
complete	bool	Flag to indicate if the round trip was completed
time_init	string	Date/time representations of the test initialization
time_term	string	Date/time representing the end of the test. In the case of SMTP monitors if a response was never received this will be null
utc_mktime	integer	Unix timestamp (seconds since epoch) of the test initialization
utc_time_init	string	Date/time of the test initialization in UTC
utc_time_term	string	Date/time the test was completed in UTC.

Status Filter Response - Data object

Sample Request

curl --user user@example.com:password https://api.knowledgefront.com/v1/Status/Filter/?t=3600&prefix=smtp&meta=dc:tx

Sample Response

{
    "error": null,
    "monitor_list": [
        {
            "alert_active": true,
            "alert_count": 1,
            "fail_count": 3,
            "label": "smtp-api-10dac8394c3470baef6df5f7d3eb26cf y next",
            "last_alert": {
                "alert": "3d00a283dce1b50cb0448a8a61fd1065c06df3c2f138f33470606c8b",
                "monitor": "56a34137230f8aecb8aef93c496c317e3851cf8008a70036d437c644",
                "time": "2018-07-17T11:54:16"
            },
            "last_failed": {
                "duration": null,
                "error": null,
                "flag": false,
                "time_init": "2018-07-17T11:54:16",
                "time_term": null,
                "utc_mktime": 1531853656,
                "utc_time_init": "2018-07-17T18:54:16",
                "utc_time_term": null
            },
            "last_test": {
                "duration": null,
                "error": null,
                "flag": false,
                "time_init": "2018-07-17T11:54:16",
                "time_term": null,
                "utc_mktime": 1531853656,
                "utc_time_init": "2018-07-17T18:54:16",
                "utc_time_term": null
            },
            "monitor": "56a34137230f8aecb8aef93c496c317e3851cf8008a70036d437c644",
            "test_count": 41
        }
    ],
    "path": "/v1/Status/Filter",
    "t": 7200
}

back to contents

Groups

Get Group List

Request

URL: https://api.knowledgefront.com/v1/Config/Group/
Description: Retrieve list of all group names and id's
HTTP Method: GET
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Config/Group
groups	array	List of group objects name and id

Sample Response

{
   "error": null,
   "groups": [
           {
                   "id": "8fcb961ee4db6b414a983c025fcef8a2e35d098a70ae7c9b40298b3d",
                   "name": "Group A"
           },
           {
                   "id": "a5c5e44ea01965dab7c4d60b835e789f8d02f54cd6d9267973c9f480",
                   "name": "Group B"
           },
           {
                   "id": "a9c783cdd35f111314053d694f9662d8e6ccc4086644e2096addeb3a",
                   "name": "Group C"
           }
   ],
   "path": "/v1/Config/Group/"
}

back to contents

Get Single Group Details

Request

URL: https://api.knowledgefront.com/v1/Config/Group/
Description: Retrieve a single group object
HTTP Method: GET
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Config/Group/{group id}/
id	string	Identifier for this group
name	string	Name given to group
monitors	array	List of monitors with id's and labels

Sample Response

{
   "error": null,
   "group": {
           "id": "8fcb961ee4db6b414a983c025fcef8a2e35d098a70ae7c9b40298b3d",
           "name": "Main Group",
           "monitors": [
                   {
                           "id": "56a34137230f8aecb8aef93c496c317e3851cf8008a70036d437c644",
                           "label": "smtp mx primary"
                   },
                   {
                           "id": "6f3aae86575a5548d64f62cea57d9feed5be535db5e8108bbb2e8861",
                           "label": "smtp mx secondary"
                   }
           ]
   },
   "path": "/v1/Config/Group/8fcb961ee4db6b414a983c025fcef8a2e35d098a70ae7c9b40298b3d/"
}

back to contents

Create Group

Request

URL: https://api.knowledgefront.com/v1/Config/Group/
Description: Create a new monitor group object with optional list of monitors to include in the grouping.
HTTP Method: POST

Parameters

Attribute	Type	Description	Required
name	string	Group Name	yes
monitors	array	List of monitors id's for this group. Not required	no

Response

Attribute	Type	Description
path	string	/v1/Config/Group/{group id}/
group	object	Object containing new group id, name, and list of monitors

Sample Response

{
   "error": null,
   "group": {
       "id": "30c01fa397737f292c73079a92cce1f6fe4c2d3780f6be3cc0efb556",
       "monitors": null,
       "name": "New Group Name"
   },
   "path": "/v1/Config/Group/"
}

back to contents

Modify Group

Request

URL: https://api.knowledgefront.com/v1/Config/Group/{group id}/
Description: Modify an existing group
HTTP Method: PUT

Parameters

Attribute	Type	Description	Required
name	string	Group Name	yes
monitors	array	List of monitors id’s for this group.	no
replace	boolean	If true the list of monitors will be replaced by the new list. If false the list of monitors will be added to the existing	no - default false

Response

Attribute	Type	Description
path	string	/v1/Config/Group/
replace	boolean	Echo of the given replace parameter
group	object	Current group object after the operation

back to contents

Delete Group

Request

URL: https://api.knowledgefront.com/v1/Config/Group/{group id}/
HTTP Method: DELETE
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Config/Group/{monitor id}/
name	string	Name of deleted group
id	string	ID of deleted group

back to contents

Monitors

Get Monitor List

Request

URL: https://api.knowledgefront.com/v1/Config/Monitor/
Description: Retrieve all monitor configurations
HTTP Method: GET
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Config/Monitor/ the current request path
monitor_list	array	List of monitor objects
monitor_list[INDEX]	object	See Get Single Monitor for details of individual monitor object attributes

back to contents

Get Single Monitor

Request

URL: https://api.knowledgefront.com/v1/Config/Monitor/{monitor id}/
Description: Retrieve a single monitor's configuration
HTTP Method: GET
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Config/Monitor/{monitor id}/ the current request path
monitor	object	The monitor object itself
monitor.alerts	array	List of alert identifiers
monitor.data_label	string	Description of data label (seconds or milliseconds typically)
monitor.hostname	string	The hostname or ip address of the monitor. For SMTP monitors may also be MX for MX record lookups.
monitor.id	string	unique identifier for the monitor
monitor.label	string	user defined name of the monitor
monitor.time_zone	string	time zone of the monitor
monitor.timer	integer	How frequently the test is run. In minutes
monitor.type	string	Type of monitor

Sample Request

curl --user email@example.com:password https://api.knowledgefront.com/v1/Config/Monitor/7c69ea44af255acddd821/

Sample Output

{
    "error": null,
    "monitor": {
            "alerts": [
                "f617675addc106f6b440f0ead2538736c92d"
            ],
            "data_label": "milliseconds",
            "hostname": "srv03.kfront.net",
            "id": "7c69ea44af255acddd821b",
            "label": "srv03 ping",
            "time_zone": "US/Central",
            "timer": "1",
            "type": "Ping"
    },
    "path": "/v1/Config/Monitor/7c69ea44af255acddd821/"
}

back to contents

Create Monitor - SMTP

Request

URL: https://api.knowledgefront.com/v1/Config/Monitor/
Description: Create a new monitor.
HTTP Method: POST

Create Monitor Parameters

Attribute	Type	Description	Required
type	string	The type must be smtp for smtp monitors. Other monitor types will be supported shortly.	yes
label	string	Label used for monitor	yes
timer	integer	How often the test messages will be sent in minutes. Valid choices are 3, 5, 10, 15, 20, 30.	yes
time_zone	string	Time zone for reporting purposes. Entries taken from the Olson tz database http://en.wikipedia.org/wiki/Tz_database. A few examples would be US/Central US/Pacific America/New_York. For a complete list see Common Time Zone List	yes
ip_address	string	This can be a hostname, ip address, or one of the following mx mx:failover See SMTP Monitor Settings for more details on the MX record options	yes
test_account	string	The email address where the test emails will be sent.	yes
use_tls	string	Choose whether TLS encryption is required for the test. Defaults to auto off on auto	no
attachment	string	Type of attachment to include with each test. Exclude for no attachment. docx for a plain word document pdf for a pdf document	no
custom_subject	string	Insert this string before the standard test message subject line	no
custom_body	string	Insert this string before the standard test body	no
ttl	integer	Time To Live for the message to make its round trip. If a test has not responded within TTL seconds it will be marked as a failure, even if it is received at a later time. Valid choices are 0 (no TTL), 30, 60, 180, 300, 600, 1800.	no
ipv6	boolean	Defaults to false if no given. Tests will only use IPv6 for delivery and will not attempt to use IPv4. If false IPv4 will be used.	no
message_format	string	Defaults to text/plain if not specified. This sets the mime-type of the test message. text/plain text/html	no
port	integer	Defaults to 25. TCP Port used for test message delivery	no
meta	object (key: value as text)	empty	no

Response

Attribute	Type	Description
path	string	/v1/Config/Monitor/ the current path
error	string	If any error occurs it should be reported here
monitor	object	Echo of the newly created monitor object. See Get Single Monitor

Sample Request

Example of creating a monitor using curl and reading the json from stdin

curl --user user@example.com:password https://api.knowledgefront.com/v1/Config/Monitor/ \
    -H "Content-Type: application/json" -X POST -d @-<<EOF
{
    "label": "SMTP Test",
    "use_tls": "on",
    "attachment": null,
    "test_account": "test@example.com",
    "ip_address": "mx:failover",
    "type": "smtp",
    "time_zone": "US/Central",
    "timer": 5,
            "meta": {"dc": "mn"}
}
EOF

Sample Output

{
       "path": "/v1/Config/Monitor"
       "error": null,
       "monitor": {
                           "alerts": [],
                           "attachment": null,
                           "custom_body": "",
                           "custom_subject": "",
                           "data_label": "seconds",
                           "id": "282def526998",
                           "ip_address": "mx:failover",
                           "label": "SMTP Test",
                           "test_account": "test@example.com",
                           "time_zone": "US/Central",
                           "timer": 5,
                           "type": "SMTP",
                           "use_tls": "on",
                                                           "meta": {"dc": "mn"}
       }
}

back to contents

Modify Monitor - SMTP

Request

URL: https://api.knowledgefront.com/v1/Config/Monitor/{monitor id}/
Description: Modify an existing monitor. Similar to Create Monitor - SMTP with the addition of an existing monitor id to modify in the path and changing the HTTP method to a PUT. Only attributes given will be updated. It is not necessary to PUT the entire config if updating just the timer for example.
HTTP Method: PUT
Modify Monitor Parameters: See Create Monitor - SMTP parameters none of which are required when updating the monitor. Only given fields will be updated and all others will remain the same.

Response

Attribute	Type	Description
path	string	/v1/Config/Monitor/
error	string	If any error occurs it should be reported here
monitor	object	Echo of the modified monitor object. See Get Single Monitor

Sample Request

Example modifying a SMTP monitor

{
        "use_tls": "on",
        "attachment": "docx",
        "test_account": "test@example.com",
        "time_zone": "US/Central",
        "timer": 5
}

back to contents

Delete Monitor

Request

URL: https://api.knowledgefront.com/v1/Config/Monitor/{monitor id}/
Description: Delete the monitor identified by the monitor id
HTTP Method: DELETE
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Config/Monitor/{monitor id}/
error	string	Any error that occurred
monitor	object	Echo of the monitor that has been deleted. See Get Single Monitor

back to contents

Alerts

Get Alert List

Request

URL: https://api.knowledgefront.com/v1/Config/Alert/
Description: Retrieve all alert configurations
HTTP Method: GET
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Config/Alert/ the current request path
alert_list	array	List of alert objects. See Get Single Alert for details of individual alert object attributes."

Sample Response

{
        "alert_list": [
                {
                        "alert_destinations": [
                                "cc057654011efe5d50993c3a4563770db2612d9362396a9d50",
                                "c95fd6b0fcf0cbcc8b4ca420068349a0ebe174127013b86554",
                                "ddfc60f234cbeb412ac4fa00b7ffd5cba978e29e796ba74143"
                        ],
                        "down_only": false,
                        "id": "35a64d822d3fd90e771cf163cf99ff90916c5124ff0",
                        "message_init": "mx03 not pingable",
                        "message_term": "mx03 pinging",
                        "monitor": "81169e8496ed65a467036cac5989167fb7700b",
                        "repeat": true,
                        "subject_init": "mx03 ping failed",
                        "subject_term": "mx03 ping responding again",
                        "type": "Up/Down Alert",
                        "violations": "1"
                },
                {
                        "alert_destinations": [
                                "cc057654011efe5d50993c3a4563770db2612d9362396a9d50"
                        ],
                        "down_only": false,
                        "id": "780fdb10a8b4bf5fabcd4514d78f6bb1875b85",
                        "message_init": "",
                        "message_term": "",
                        "monitor": "7553eeda01b0c1cc4cd3baabc5d47e7720631888d28",
                        "repeat": true,
                        "subject_init": "dns Detected down",
                        "subject_term": "dns Detected up",
                        "type": "Up/Down Alert",
                        "violations": "1"
                },
        ]
        "error": null,
        "path": "/v1/Config/Alert/"
}

back to contents

Get Single Alert

Request

URL: https://api.knowledgefront.com/v1/Config/Alert/{alert id}/
Description: Get a single alert's configuration
HTTP Method: GET
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Config/Alert/ the current request path
alert	object	The alert object retrieved
alert.alert_destinations	array	ID list of the alert destinations. Where this alert will be sent when triggered or reset
alert.down_only	boolean	When true this alert will only send down notifications. Up will be recorded, but not sent to the alert destinations
alert.id	string	Unique identifier for this alert object
alert.message_init	string	Message body when alert is triggered
alert.message_term	string	Message body when alert is reset
alert.subject_init	string	Subject of alert message when alert is triggered
alert.timeout	integer	Minutes that responses must fail before the alert will trigger
alert.type	string	Type of alert. Currently only SMTP alerts are supported. More updates coming soon.

Sample Request

curl --user email@example.com:password https://api.knowledgefront.com/v1/Config/Alert/2bd333f096e53f9809/

Sample Response

{
    "alert": {
        "alert_destinations": [
            "c95fd6b0fcf0cbcc8b4ce0ff77a420068349a0ebe174127013b86554",
            "ddfc60f234cbeb412ac4920d6cfa00b7ffd5cba978e29e796ba74143",
            "9a38370e6c3f179c9842e1f9799d5280d9e5c8355523a103d840df49"
        ],
        "down_only": false,
        "id": "2bd333f096e53f9809",
        "message_init": "mx03 tests are failing. View reports at https://www.knowledgefront.com/",
        "message_term": "mx03 is responding normally to Knowledge Front tests",
        "monitor": "d9c69a74039101a94e88cb5cd964da65aa214a",
        "repeat": true,
        "subject_init": "mx03 SMTP not responding",
        "subject_term": "mx03 SMTP responding to external monitoring",
        "timeout": 5,
        "type": "up-down"
    },
    "error": null,
    "path": "/v1/Config/Alert/2bd333f096e53f9809/"
}

back to contents

Create Alert

Request

URL: https://api.knowledgefront.com/v1/Config/Alert/
Description: Create a new alert
HTTP Method: POST

Common Create Alert Parameters

AttributeType	Description	Required
type	string	Currently must be up-down - more alert types will be supported in the API soon. yes
monitor	string	Monitor this alert is assigned to	yes monitor.id yes
alert_destinations	array of strings	When this alert triggers or resets it will be delivered to these alertdestination.id’s	no
subject_init	string	Subject text sent when alert is triggered	yes
subject_term	string	Subject text sent when the alert is reset	yes
message_init	string	Text of the body when the alert is triggered.	no
message_term	string	Text of the body sent when the alert is reset.	no
down_only	boolean	If true this alert will only send messages when the alert is triggered.	The reset will be recorded, but not delivered to the alert destination list	no
repeat	boolean	When true the alert will continue to trigger while the alert condition is true.	See Network Alerting for more information.	no

SMTP Specific Alert Parameters

Attribute	Type	Description	Required
timeout	integer	Time in minutes that responses must fail before the alert will trigger. See SMTP Alerting for more details on how alerts are triggered.	yes

Sample Create Alert Request

This is an SMTP alert example

{
        "down_only": false,
        "repeat": true,
        "monitor": "4877602b9f202b5a1370f777d7364d555f",
        "timeout": 5,
        "alert_destinations": [
                "cc057654011efe5d509918e8d93c3a4563770db26",
                "ddfc60f234cbeb412ac4920d6cfa00b7ffd5cba97",
                "c95fd6b0fcf0cbcc8b4ce0ff77a420068349a0ebe"
        ],
        "type": "up-down",
        "subject_init": "mx03 not responding"
        "subject_term": "mx03 responding again",
        "message_term": "mx03 tests are failing. Take immediate action",
        "message_init": "mx03 tests are working again. Relax and enjoy the view.",
}

Sample Create Alert Response

{
    "alert": {
            "alert_destinations": [
                "c95fd6b0fcf0cbcc8b4ce0ff77a420068349a0ebe",
                "ddfc60f234cbeb412ac4920d6cfa00b7ffd5cba97",
                "cc057654011efe5d509918e8d93c3a4563770db26"

            ],
            "down_only": false,
            "id": "0dcdade03fa9c64fc4514ceddefa2696d66b75638211a12e8e057d53",
            "message_init": "mx03 tests are failing. Take immediate action",
            "message_term": "mx03 tests are working again. Relax and enjoy the view.",
            "monitor": "4877602b9f202b5a1370f777d7364d555f",
            "repeat": true,
            "subject_init": "mx03 not responding",
            "subject_term": "mx03 responding again",
            "timeout": 5,
            "type": "up-down"
        },
        "error": null,
        "path": "/v1/Config/Alert/"
}

Modify Alert

Request

URL: https://api.knowledgefront.com/v1/v1/Config/Alert/{alert id}/
Description: Modify an existing alert identified by the alert id give in the path.
HTTP Method: PUT
Parameters: See Create Alert parameters for the specific type of alert. The json body is identical

back to contents

Delete Alert

Request

URL: https://api.knowledgefront.com/v1/Config/Alert/{alert id}/
Description: Delete an existing alert from the system.
HTTP Method: DELETE
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Config/Alert/{alert id}/
error	string	Should any errors occur they will be reported here.
alert	object	Echo of the alert object that was deleted. See Get Single Alert

back to contents

Pause Alerting

Get Paused Alerts

Request

URL: https://api.knowledgefront.com/v1/Pause/Alert/
Description: Get a list of all paused alert id’s and their duration
HTTP Method: GET
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Pause/Alert/
alert_list	array	List of paused alert objects
alert_list[INDEX].id	string	Unique id of the alert
alert_list[INDEX].seconds	integer	Seconds remaining before the alert is enabled
alert_list[INDEX].monitor	string	Unique id of the monitor that belongs to this alert

Sample Response

{
    "alert_list": [
        {
            "id": "ceca10cece1cd1d5d9cc9f62df6a76864f9e4f",
            "monitor": "67c5e0357f76df65d24ff83accb8332adf6",
            "seconds": 3596
        }
    ],
    "error": null,
    "path": "/v1/Pause/Alert/"
}

Pause All Alerts

Request

URL: https://api.knowledgefront.com/v1/Pause/Alert/
Description: Pause all alerts for a specified timeframe
HTTP Method: POST

Parameters

Attribute	Type	Description	Required
seconds	integer	Time, in seconds, the alert will be paused. The alert becomes active again after the time has elapsed.	yes

Response

Attribute	Type	Description
path	string	/v1/Pause/Alert/
error	string	Any error that may have occurred. null if no error
alert_list	array	List of alert id's that have been paused
seconds	integer	Echo of seconds from the request. Time alerts will be paused.

Sample Request

curl --user test@example.com:password https://api.knowledgefront.com/v1/Pause/Alert/ \
         -H "Content-Type: application/json" -X POST -d @-<<EOF
{
        "seconds": 1200
}
EOF

Sample Response

{
    "alert_list": [
            "ceca10cece1cd1d5d9cc9f62df6a76864f96a2a4572b",
            "4c6f857e3503f60a6fa878475090459dc89389aeeaa4",
            "1c3fe060aff7188d3dc3615731df3480391325f3449b"
    ],
    "error": null,
    "path": "/v1/Pause/Alert/",
    "seconds": 1200
}

back to contents

Pause Single Alert

Request

URL: https://api.knowledgefront.com/v1/Pause/Alert/{alert id}/
Description: Pause alerting for an individual alert.
HTTP Method: POST

Parameters

Attribute	Type	Description	Required
seconds	integer	Time, in seconds, this alert will be paused. The alert will become active after the time has elapsed.	yes

Response

Attribute	Type	Description
path	string	/v1/Pause/Alert/{monitor id}/
error	string	Any error that may have occurred. null if no error
alert	string	Unique id of the alert that was paused
monitor	string	Unique id of the monitor belonging to this alert
seconds	integer	Echo of seconds from the request. Time alerts will be paused.

Sample Request

curl --user user@example.com:password https://api.knowledgefront.com/v1/Pause/Alert/282def52699812f71f1cc91dd9/ \
         -H "Content-Type: application/json" -X POST -d @-<<EOF
{
     "seconds": 1200
}
EOF

back to contents

Pause Monitor Alerts

Request

URL: https://api.knowledgefront.com/v1/Pause/Monitor/{monitor id}/
Description: Pause all alerts for the given monitor
HTTP Method: POST

Parameters

Attribute	Type	Description	Required
seconds	integer	Time, in seconds, the alerts for this monitor will be pause. Alerts will become active after the time has elapsed.	yes

Response

Attribute	Type	Description
path	string	/v1/Pause/Monitor/{monitor id}/
error	string	Error description that occurred. null if no error
alert_list	array	List of alert id's that have been paused by this command
seconds	integer	Echoing the seconds given in the request. Seconds from now that the alert will remain paused.

Sample Request

curl --user user@example.com:password https://api.knowledgefront.com/v1/Pause/Monitor/f2aca5d1b790abc472e82c7dd/ \
            -H "Content-Type: application/json" -X POST -d @-<<EOF
{
        "seconds": 1200
}
EOF

back to contents

Enable All Alerts

Request

URL: https://api.knowledgefront.com/v1/Pause/Alert/
Description: Delete any pauses previously placed on alerts causing alerting to resume.
HTTP Method: DELETE
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Pause/Alert/
error	string	Any error that may have occurred. null if no error
alert_list	array	Array of alert id's that were processed during the operation

back to contents

Enable Alerting - Monitor

Request

URL: https://api.knowledgefront.com/v1/v1/Pause/Alert/{monitor id}/
Description: Enable all alerts for the monitor given by {monitor id}
HTTP Method: DELETE
Parameters: None

Response

See Enable All Alerts the response format is the same. The alert_list returned will be the id’s of the alerts associated with the given monitor.

back to contents

Alert Destinations

Get Alert Destination List

Request

URL: https://api.knowledgefront.com/v1/Config/AlertDestination/
Description: Retrieve a list of all Alert Destination configurations
HTTP Method: GET
Parameters: None

Response

Attribute	Type	Description
path	string	/v1/Config/AlertDestination/
alertdestination_list	array	List of alert destination objects. See Get Single Alert Destination for details of individual object attributes.

back to contents

Get Single Alert Destination

Request

URL: https://api.knowledgefront.com/v1/Config/AlertDestination/{alert destination id}/
Description: Get a single alert destination's configuration
HTTP Method: GET
Parameters: None

Response

Attribute	Type	Description
path	string	`/v1/Config/AlertDestination/{ alert destination id}/`
alertdestination	object	The alert destination object retrieved
alertdestination.id	string	Unique identifier for this destination
alertdestination.destination	string	The phone number or ip address of the destination
alertdestination.label	string	Human readable label to easily identify the alert destination
alertdestination.subscribed	boolean	If the owner of the destination has opted out of receiving alerts this will be false
alertdestination.type	string	One of email, sms, or voice

Sample Response

{
    "alertdestination": {
        "destination": "test@example.com",
        "id": "ddfc60f234cbeb412ac4920d6cfa00b7ffd5cba978e29e796ba",
        "label": "Email Destination",
        "subscribed": true,
        "type": "EMAIL"
    },
    "error": null,
    "path": "/v1/Config/AlertDestination/ddfc60f234cbeb412ac4920d6cfa00b7ffd5cba978e29e796ba/"
}

back to contents

Data

Get All Monitor Data

Request

URL: https://api.knowledgefront.com/v1/Data/Monitor/
Description: Retrieve data for all monitors or filter for select monitor data

Parameters

Attribute	Type	Description	Required
begin	integer	Timestamp as seconds since the epoch. The starting point for pulling data. Defaults to one hour if not given.	no defaults to one hour ago
end	integer	Timestamp as seconds since the epoch. If not given the current time is used for the end of the reporting time frame	no defaults to current time
average	string	One of hour day or raw. Defaults to raw if not given.	no defaults to raw
meta	string	Filter monitors by the meta data attributes. Example: ?meta=key1:value1,key2:value2	no

Get Single Monitor Data

Request

URL: https://api.knowledgefront.com/v1/Data/Monitor/{monitor id}/
Description: Get data for an individual monitor for a time period
HTTP Method: GET

Parameters

Attribute	Type	Description	Required
begin	integer	Timestamp as seconds since the epoch. The starting point for pulling data. Defaults to one hour if not given.	no defaults to one hour ago
end	integer	Timestamp as seconds since the epoch. If not given the current time is used for the end of the reporting time frame.	no defaults to current time
average	string	One of hour day or raw. Defaults to raw if not given.	no defaults to raw

Response

Monitor Data Response

Attribute	Type	Description
path	string	/v1/Data/Monitor/{monitor id}/
error	string	Any error that may have occurred. null if no error
begin	integer	The beginning of the requested time frame.
end	integer	The end of the requested time frame.
monitor	string	The id of the monitor
monitor_label	string	User defined label given to monitor
data	array	Array of individual data objects. See table below.

Data Items

Attribute	Type	Description
alert_matches	array	Array of alert id’s. When an alert violation condition matches this data point its id is added to this list. Not currently used for SMTP monitors
error	string	Any error recorded for this data point
failed	boolean	True if this test failed to complete regardless if any alert conditions were matched.
samples	integer	Used for hourly and daily averages. The number of tests in the average period
time	string	ISO formatted date string with timezone conversion. example: 2016-04-06T14:59:16
utc_mktime	integer	Time stamp (Seconds since Epoch) with no timezone offset.
utc_time	string	ISO formatted date string in UTC example: 2016-04-06T19:59:16
value	float	The value of the recorded test. Typically the response time in milliseconds. 2 seconds would be 2000.0

Sample Request

Get the last hour’s data

curl --user user@example.com:password https://api.knowledgefront.com/v1/Data/Monitor/282def52699812f71f1cc91dd9470b59/

Get the last sixty days worth of data with hourly averages

now=`date +%s`
sixty_days=`echo "$now - (86400 * 60)" | bc`
curl --user user@example.com:password \
    https://api.knowledgefront.com/282def52699812f71f1cc91dd9470b59/?begin=$sixty_days\&average=hour

back to contents

Get SMTP Response Analysis

Request

URL: https://api.knowledgefront.com/v1/Data/Monitor/Response/{monitor id}/
Description: Get the header analysis for SMTP response messages
HTTP Method: GET

Parameters

Attribute	Type	Description	Required
begin	integer	Timestamp as seconds since the epoch. The starting point for pulling data. Defaults to one hour if not given.	no defaults to one hour ago
end	integer	Timestamp as seconds since the epoch. If not given the current time is used for the end of the reporting time frame.	no defaults to current time

Response

Attribute	Type	Description
path	string	/v1/Data/Monitor/{monitor id}/
error	string	Any error that may have occurred. null if no error
begin	integer	The beginning of the requested time frame.
end	integer	The end of the requested time frame.
analysis	list	List of list of response objects which contain the from, to, and time for each header in the test message

Sample Response

{
   "path": "/v1/Data/Monitor/Response/4c58505dd25784572bd3a91063b1c6a87c66e/",
   "begin": 1565658260,
   "end": 1565658560,
   "analysis": [
           [
                   {
                           "source": "mx01.ga.kfnm.us",
                           "destination": "tx01.kfront.net",
                           "time": 1565658260,
                           "duration": 2
                   },
                   {
                           "source": "localhost",
                           "destination": "tx01.kfront.net",
                           "time": 1565658260,
                           "duration": 4
                   },
                   {
                           "source": "tx01.kfront.net",
                           "destination": "kf01.knowledgefront.com",
                           "time": 1565658260,
                           "duration": 3
                   },
                   {
                           "source": "localhost",
                           "destination": "kf01.knowledgefront.com",
                           "time": 1565658260,
                           "duration": 0
                   },
                   {
                           "source": "kf01.knowledgefront.com",
                           "destination": "mx01.ga.kfnm.us",
                           "time": 1565658260,
                           "duration": 1
                   }
           ]
   ],
   "error": null
}

back to contents

API Version 1

Table of Contents

Authentication

Alert Status Summary

Get Alert Status List

Sample Request

Sample Output

Status Filter Summary

Request

Response

Sample Request

Sample Response

Groups

Get Group List

Request

Response

Get Single Group Details

Request

Response

Create Group

Request

Response

Modify Group

Request

Response

Delete Group

Request

Response

Monitors

Get Monitor List

Request

Get Single Monitor

Request

Response

Create Monitor - SMTP

Request

Response

Modify Monitor - SMTP

Request

Response

Delete Monitor

Request

Response

Alerts

Get Alert List

Request

Response

Get Single Alert

Request

Response

Create Alert

Request

Modify Alert

Request

Delete Alert

Request

Response

Pause Alerting

Get Paused Alerts

Request

Response

Pause All Alerts

Request

Response

Pause Single Alert

Request

Response

Pause Monitor Alerts

Request

Response

Enable All Alerts

Request

Response

Enable Alerting - Monitor

Request

Response

Alert Destinations

Get Alert Destination List

Request

Response