Knowledge Front Logo
Back to knowledgefront.com Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
  1. Knowledge Front Help
  2. /
  3. Knowledge Front HTTP API
  4. /
  5. API Version 1

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
error string Description of any error that occured processing the request
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.attachment string docx or pdf for type of attachment
monitor.custom_body string Customized text included with each smtp test message body
monitor.custom_subject string Customized text included in each test message subject line
monitor.data_label string Description of data label (seconds or milliseconds typically)
monitor.description string Additional field for further description of the monitor outside the label itself
monitor.groups array Array of group id strings to which this monitor belongs
monitor.ip_address 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.ipv6 bool If true then ipv6 will be used for delivery
monitor.label string user defined name of the monitor
monitor.message_format string One of text/html or text/plain
monitor.meta object Key/value strings for additional filtering
monitor.port integer TCP Port number to use for delivery (default 25)
monitor.test_account string Email address to use for test message delivery
monitor.time_zone string time zone of the monitor
monitor.timeout integer Time in seconds to wait on idle TCP connections
monitor.timer integer How frequently the test is run. In minutes
monitor.ttl integer Seconds before message is counted as failed before receiving a reply
monitor.type string Type of monitor (smtp)
monitor.use_client_cert bool If true a client side certificate will be provided when making a TLS connection
monitor.use_tls string Choose whether TLS encryption is required for the test. One of on/off/auto

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

AttributeTypeDescriptionRequired
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

{
  "error": null,
  "monitor": {
    "alerts": [
      "0454224ddf384f7f7dd2c0091c15729de1c44b03ca361291df8f9793",
      "09b49a7986a3ce8eb972b434ec9a87bb7be86d8781349ac4c352df10",
      "dbf0a90e81f17f32524b2e7c48901450c7e8e8122b867a511bea57c5"
    ],
    "attachment": "",
    "custom_body": "",
    "custom_subject": "",
    "data_label": "seconds",
    "description": null,
    "groups": [
      "b9b102ac572bd2136ac1b6b26382e1d05003a8390e797fc28697a6a2",
      "f4186d65df509c421da927405c404c178b9e14936050401997c55769",
      "a5c5e44ea01965dab7c4d60b835e789f8d02f54cd6d9267973c9f480"
    ],
    "id": "fff2eb198f8c17fe50f3fec9c694c1d809738116babfe61f6a269f5d",
    "ip_address": "127.0.0.1",
    "ipv6": false,
    "label": "smtp-api-b23de16dcad95bb3906f641dec66aa24 y realty",
    "message_format": "text/html",
    "meta": {
      "api": "test"
    },
    "port": 25,
    "test_account": "mailtest1@local.kfnm.us",
    "time_zone": "US/Central",
    "timeout": 0,
    "timer": 5,
    "ttl": 30,
    "type": "smtp",
    "use_client_cert": false,
    "use_tls": "auto"
  },
  "path": "/v1/Config/Monitor/fff2eb198f8c17fe50f3fec9c694c1d809738116babfe61f6a269f5d/"
}

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

gdoc_arrow_left_alt Knowledge Front HTTP API Network Monitor Types gdoc_arrow_right_alt