NAV
shell

Introduction

To get started using Webmon’s API, login to your account and generate an API key from Account Settings page. There are 2 API key types:

Webmon’s API endpoint is api.webmon.com/v1/

Authentication

Webmon’s API uses OAuth2 bearer to authenticate requests. All requests require Bearer Authorization header with a key generated from your Account Settings page.

curl api.webmon.com/v1/locations\
 -H "Authorization: Bearer <token>"

Targets

List Targets

GET /v1/targets/

Response

A list of target objects.

curl api.webmon.com/v1/targets/\
 -H "Authorization: Bearer <token>"
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 163,
      "locations": [
        5,
        1
      ],
      "escalation": 40,
      "depends_on": [],
      "properties": {
        "follow_redirect": true,
        "timeout_ms": 60000,
        "url": "https://www.google.com/",
        "detect_by_location": false,
        "expected_response_code": [
          200
        ],
        "headers": [],
        "method": "get"
      },
      "type": {
        "name": "http",
        "properties": {
          "values": [
            {
              "value_id": 0,
              "unit": "Milliseconds",
              "name": "DNS Lookup"
            },
            {
              "value_id": 1,
              "unit": "Milliseconds",
              "name": "Connect time"
            },
            {
              "value_id": 2,
              "unit": "Milliseconds",
              "name": "Response Time"
            },
            {
              "value_id": 3,
              "unit": "KBit/sec",
              "name": "Throughput"
            }
          ],
          "combined_values": [
            0,
            1,
            2
          ]
        }
      },
      "last_outage_24h": "11 days 14 hours, 52 minutes",
      "uptime_24h": [
        0,
        100,
        0
      ],
      "current_state": {
        "state": "error",
        "reason": "String \"bad target\" not found in body",
        "begin_time": 1473186728,
        "end_time": 1474190643,
        "duration": "278 hours, 51 minutes"
      },
      "created": "Apr 09, 16 at 07:10 +0000",
      "modified": "Sep 07, 16 at 19:00 +0000",
      "status": "E",
      "name": "google",
      "frequency": 60,
      "state": "error",
      "tags": "google"
    }
  ]
}

Create Target

POST /v1/targets/

Response

Target object.

JSON Request

Field Description
name required target name
type_id required Type of target to monitor. Values are one of http, icmp, smtp, tcp, ftp, dns, multi_http.
locations required One or more location IDs to check the target from.
properties required Object specifying target’s configuration based on type_id’s value. Check fields requirements below based on the type_id you specify.
escalation optional Escalation ID to use when creating an incident.
tags optional space delimited keywords that can be used to group targets.
frequency optional, default is 60 Frequency at which to check the target. Values allowed: 30, 60.
depends_on optional List of target IDs that this target depends on. If one of the targets in the depends_on is unhealthy then this target will not trigger creating an incident.
status optional, default is E Enable or Disable the target on creation. Values allowed: E, D

All the fields below belong to the properties object. Pass in the required fields based on the type_id you’ve specified.

Common Properties

Those are the common fields that can be used for all type_ids.

Field Description
timeout_ms optional, default 60000 Timeout value in milliseconds. Values allowed: 5000, 10000, 20000, 30000, 60000.
detect_by_location optional, default is false Detect outage by location. If enabled, an incident is opened if any of the locations the target is being monitored from cannot reach the target.
webhook_url optional Callback URL to post target status changes.
Target Status object:
{"target_id": 1, "host": <URL or host of target>, "state": <reachable,unreachable,error>, "error":<set when state=error>}.

HTTP Properties

Field Description
url required target URL. Can start with either http:// or https//.
method optional, default is get HTTP method to use. Values allowed: get, post, put, head, options
expected_response_code optional, default [200] A list of HTTP response codes to expect.
expected_body_string optional A string to expect in the response.
headers optional, default is [] Array of strings that will be appended as headers in the request. Example: ["host: example.com",]
follow_redirect optional, default is true Follow 3xx responses.
form_data optional HTTP body content to send with request. The data is sent as is.
username optional HTTP username authentication
password optional HTTP password authentication

DNS Properties

Field Description
host required DNS server’s IP Address.
port optional, default is 53 DNS Server’s port.
query required DNS query value to send. example: google.com.
query_type required DNS query type to send. Values allowed: a, ptr, cname, mx.
expected_responses required Array of strings to match against the response answers. At least one of the values should match the answers to consider it healthy.

TCP Properties

Field Description
host required Target’s fqdn or IP Address.
port required TCP port to connect on.
data_to_send optional, default is null Data to send after connect.
data_to_send_b64 optional, default is false If set, agent tries to decode data_to_send from base64 and sends the binary result.
expected_response optional If set, agent searches for string in response. If found, the check is considered healthy.
bytes_to_read optional if expected_response is not set Number of bytes to read if expected_response is set.

ICMP Properties

Field Description
host required Target’s fqdn or IP Address.

SMTP Properties

Field Description
url required SMTP URL formatted as smtp(s)://[username:password]@<host>:<port> .

FTP Properties

Field Description
url required target FTP URL formatted as ftp://[username:password]@<host>:<port>/<path> .
curl api.webmon.com/v1/targets/\
 -H "Content-Type: application/json"\
 -H "Authorization: Bearer <token>"\
 -d @- << EOF
{
  "name": "my new target",
  "locations": [1],
  "type_id": "http",
  "properties": {
    "url": "http://google.com"
  }
}
EOF
{
  "id": 191,
  "locations": [
    1
  ],
  "escalation": null,
  "depends_on": [],
  "properties": {
    "expected_response_code": [
      200
    ],
    "method": "get",
    "url": "http://google.com",
    "follow_redirect": true,
    "detect_by_location": false,
    "timeout_ms": 60000
  },
  "type": {
    "name": "http",
    "properties": {
      "preview_value_id": 2,
      "values": [
        {
          "value_id": 0,
          "unit": "Milliseconds",
          "name": "DNS Lookup"
        },
        {
          "value_id": 1,
          "unit": "Milliseconds",
          "name": "Connect time"
        },
        {
          "value_id": 2,
          "unit": "Milliseconds",
          "name": "Response Time"
        },
        {
          "value_id": 3,
          "unit": "KBit/sec",
          "name": "Throughput"
        }
      ],
      "combined_values": [
        0,
        1,
        2
      ]
    }
  },
  "last_outage_24h": null,
  "uptime_24h": [
    100,
    100,
    1
  ],
  "current_state": {},
  "created": "Sep 18, 16 at 20:10 +0000",
  "modified": "Sep 18, 16 at 20:10 +0000",
  "status": "E",
  "name": "my new target",
  "frequency": 60,
  "state": "unknown",
  "tags": null
}

Update Target

PUT /v1/targets/{target_id}/

Fields required to update a target are the same as for creating one with the exception of properties field which isn’t required if it doesn’t need to be modified.

Response

Target object.

Delete Target

DELETE /v1/targets/{target_id}/

Permanently deletes a target.

Test New Target

PUT /v1/targets/test/

Runs a single test check and returns its result. Takes same parameters for creating a target.

curl api.webmon.com/v1/targets/test/\
 -H "Content-Type: application/json"\
 -H "Authorization: Bearer <token>"\
 -X PUT -d @- << EOF

{
  "name": "my new target",
  "locations": [1],
  "type_id": "http",
  "properties": {
    "url": "http://google.com"
  }
}
EOF
{"success":true}

Test Existing Target

PUT /v1/targets/{target_id}/test/

Runs a single test check on an existing target and returns its result.

curl api.webmon.com/v1/targets/163/test\
 -H "Content-Type: application/json"\
 -H "Authorization: Bearer <token>"\
 -X PUT 
{
  "error": "String \"bad target\" not found in body"
}
curl api.webmon.com/v1/targets/149/test\
 -H "Content-Type: application/json"\
 -H "Authorization: Bearer <token>"\
 -X PUT 
{"success":true}

Enable Target

PUT /v1/targets/{target_id}/enable/

Enables a target to get checked by our agents.

Response

Target object.

Disable Target

PUT /v1/targets/{target_id}/disable/

Stops target from being checked by our agents.

Response

Target object.

Target Metrics

Get Target Metrics

GET /v1/targets/metrics/{target_id}/

GET /v1/targets/metrics/

Get target measurements and availability for a target.

Query Parameters

Field Description
targets optional, defaults to all targets A comma separated list of target IDs to return. This value is ignored if {target_id} is specified.
time_range optional, defaults to last 5 mins Specifies the time range of measurements returned. Values allowed: min_5, min_30, hour_1, hour_3, hour_12, day_1, day_3, week_1, month_1, month_3, month_6, year_1.
availability_range optional, default 1 week Calculates the availability based on the range specified. Values allowed: week_1, month_6, year_1.
curl api.webmon.com/v1/targets/149/\
 -H "Authorization: Bearer <token>"
{
  "id": 149,
  "outages": [],
  "availability": [
    {
      "date": "Sep 14",
      "states": [],
      "uptime": 100,
      "current_status": 1,
      "coverage": 100
    },
    {
      "date": "Sep 15",
      "states": [],
      "uptime": 100,
      "current_status": 1,
      "coverage": 100
    },
    {
      "date": "Sep 16",
      "states": [],
      "uptime": 100,
      "current_status": 1,
      "coverage": 100
    },
    {
      "date": "Sep 17",
      "states": [],
      "uptime": 100,
      "current_status": 1,
      "coverage": 100
    },
    {
      "date": "Sep 18",
      "states": [],
      "uptime": 100,
      "current_status": 1,
      "coverage": 100
    },
    {
      "date": "Sep 19",
      "states": [],
      "uptime": 100,
      "current_status": 1,
      "coverage": 100
    },
    {
      "date": "Sep 20",
      "states": [],
      "uptime": 100,
      "current_status": 1,
      "coverage": 100
    }
  ],
  "values": [
    {
      "values": [
        [
          0,
          22,
          408,
          923488
        ]
      ],
      "timestamp": 1474313160,
      "location_id": 5
    },
    {
      "values": [
        [
          0,
          22,
          407,
          919201
        ]
      ],
      "timestamp": 1474313220,
      "location_id": 5
    },
    {
      "values": [
        [
          0,
          22,
          574,
          707330
        ]
      ],
      "timestamp": 1474313280,
      "location_id": 5
    },
    {
      "values": [
        [
          0,
          24,
          492,
          769540
        ]
      ],
      "timestamp": 1474313340,
      "location_id": 5
    },
    {
      "values": [
        [
          0,
          22,
          498,
          765833
        ]
      ],
      "timestamp": 1474313400,
      "location_id": 5
    },
    {
      "values": [
        [
          0,
          26,
          504,
          807508
        ]
      ],
      "timestamp": 1474313220,
      "location_id": 1
    },
    {
      "values": [
        [
          0,
          22,
          522,
          795133
        ]
      ],
      "timestamp": 1474313280,
      "location_id": 1
    },
    {
      "values": [
        [
          1,
          23,
          412,
          917537
        ]
      ],
      "timestamp": 1474313340,
      "location_id": 1
    },
    {
      "values": [
        [
          0,
          23,
          455,
          874072
        ]
      ],
      "timestamp": 1474313400,
      "location_id": 1
    },
    {
      "values": [
        [
          0,
          22,
          432,
          920277
        ]
      ],
      "timestamp": 1474313460,
      "location_id": 1
    }
  ],
  "events": [],
  "type": {
    "name": "http",
    "properties": {
      "preview_value_id": 2,
      "values": [
        {
          "value_id": 0,
          "unit": "Milliseconds",
          "name": "DNS Lookup"
        },
        {
          "value_id": 1,
          "unit": "Milliseconds",
          "name": "Connect time"
        },
        {
          "value_id": 2,
          "unit": "Milliseconds",
          "name": "Response Time"
        },
        {
          "value_id": 3,
          "unit": "KBit/sec",
          "name": "Throughput"
        }
      ],
      "combined_values": [
        0,
        1,
        2
      ]
    }
  },
  "created": "Oct 10, 15 at 10:50 +0000",
  "modified": "Sep 20, 16 at 02:05 +0000",
  "status": "E",
  "name": "curl target2",
  "state": "reachable",
  "locations": [
    5,
    1
  ]
}

Escalations

List Escalations

GET /v1/escalations/

Get a list of escalations configured.

Response

A list of escalation objects.

curl api.webmon.com/v1/escalations/\
 -H "Authorization: Bearer <token>"
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 33,
      "stages": [
        {
          "id": 195,
          "contacts": [
            {
              "id": 206,
              "user": 1,
              "sms": true,
              "email": false
            },
            {
              "id": 207,
              "user": 36,
              "sms": false,
              "email": true
            },
            {
              "id": 208,
              "user": 51,
              "sms": true,
              "email": true
            }
          ],
          "name": "Stage 1",
          "stage_speed": 900,
          "notify_every": 600,
          "notify_max": 3
        }
      ],
      "pagerduty": null,
      "name": "another escalation",
      "cc_emails": ""
    },
    {
      "id": 40,
      "stages": [
        {
          "id": 193,
          "contacts": [
            {
              "id": 202,
              "user": 51,
              "sms": false,
              "email": true
            }
          ],
          "name": "Stage 1",
          "stage_speed": 180,
          "notify_every": 900,
          "notify_max": 2
        }
      ],
      "pagerduty": null,
      "name": "test",
      "cc_emails": null
    }
  ]
}

Incidents

List Incidents

GET /v1/incidents/

Get a list of incidents created.

Response

A list of incident objects.

curl api.webmon.com/v1/incidents/\
 -H "Authorization: Bearer <token>"
{
  "count": 13,
  "num_pages": 7,
  "results": [
    {
      "id": 28,
      "duration": "",
      "created": "Sep 08, 16 at 09:41 -0700",
      "actions": [
        {
          "id": 62,
          "created": "Sep 08, 16 at 09:41 -0700",
          "stage": 1,
          "action": "esc",
          "source": "internal",
          "note": "",
          "incident": 28,
          "user": null
        },
        {
          "id": 63,
          "created": "Sep 08, 16 at 09:41 -0700",
          "stage": 1,
          "action": "notify_email",
          "source": "internal",
          "note": "",
          "incident": 28,
          "user": 51
        },
        {
          "id": 64,
          "created": "Sep 08, 16 at 16:31 -0700",
          "stage": 1,
          "action": "ack",
          "source": "internal",
          "note": "",
          "incident": 28,
          "user": 1
        }
      ],
      "close_time": null,
      "state": "ack_sleeping",
      "open_reason_code": 2,
      "open_reason_text": "String \"bad target\" not found in body",
      "escalation": 40,
      "target": 163,
      "rule": null
    },
    {
      "id": 27,
      "duration": "39 minutes",
      "created": "Sep 08, 16 at 09:02 -0700",
      "actions": [
        {
          "id": 61,
          "created": "Sep 08, 16 at 09:41 -0700",
          "stage": 0,
          "action": "close",
          "source": "internal",
          "note": "",
          "incident": 27,
          "user": 1
        }
      ],
      "close_time": null,
      "state": "closed",
      "open_reason_code": 2,
      "open_reason_text": "String \"bad target\" not found in body",
      "escalation": 40,
      "target": 163,
      "rule": null
    }
  ],
  "next": 2,
  "current": 1,
  "previous": 0
}

Users

List Users

GET /v1/account/users/

Response

A list of user objects.

curl api.webmon.com/v1/account/users/\
 -H "Authorization: Bearer <token>"
{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 47,
      "is_admin": false,
      "is_operator": false,
      "is_admin_or_operator": false,
      "is_readonly": true,
      "email": "user1@example.com",
      "name": "My User 1",
      "phone": null,
      "timezone": "US/Pacific",
      "scope": "read"
    },
    {
      "id": 36,
      "is_admin": false,
      "is_operator": true,
      "is_admin_or_operator": true,
      "is_readonly": false,
      "email": "user2@example.com",
      "name": "My User 2",
      "phone": null,
      "timezone": "US/Pacific",
      "scope": "read write"
    },
    {
      "id": 1,
      "is_admin": true,
      "is_operator": false,
      "is_admin_or_operator": true,
      "is_readonly": false,
      "email": "user3@example.com",
      "name": "My User 3",
      "phone": "6502703370",
      "timezone": "US/Pacific",
      "scope": "read write admin"
    }
  ]
}

Locations

List Locations

GET /v1/locations/

Get list of locations available.

Response

A list of location objects.

curl api.webmon.com/v1/locations/\
 -H "Authorization: Bearer <token>"
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "US West",
      "country": "US",
      "state": "CA",
      "city": "San Jose"
    },
    {
      "id": 5,
      "name": "US East",
      "country": "United States",
      "state": "California",
      "city": "San Francisco"
    }
  ]
}