Monitors

Monitors are called IP monitors inside the API.

Fields

• external_ref - Arbitrary identifier used to cross reference this IP monitor with a record in your app.
• health - Current health status. (Read-only)
• health_at - Time of last health change. (Read-only)
• host_ids - Array of associated Host IDs. (Read-only)
• hostname - Hostname of monitored/target service. Required when uri is http or https.
• id - DNScaster’s ID for the IP monitor, eg: mon_sample123456. (Read-only)
• in_use - When true, ineligible to be deleted (likely in use by a host). (Read-only)
• name - A descriptive name of the IP monitor.
• nameserver_set_id - Nameserver set to which this IP monitor belongs.
• object - Always ip_monitor. (Read-only)
• treat_redirects - For http and https, treat 3xx redirects as online (default) or offline.
• uri - URI of service to monitor.

List IP monitors

Query params

• external_ref - Filter by external_ref.
• health - Filter by health.
• nameserver_set_id - Filter by nameserver_set_id.
• Plus standard paging params.
  • sort - Fields: id (default), name.

Request

GET /v1/ip_monitors

Response

On success, 200 with 0 or more IP monitors.

{
  "collection": [
    {
      "external_ref": null,
      "health": "online",
      "health_at": 1735689600,
      "host_ids": [
        "hst_sample123456"
      ],
      "hostname": "example.com",
      "id": "mon_sample123456",
      "name": "Example",
      "nameserver_set_id": "nst_sample123456",
      "object": "ip_monitor",
      "treat_redirects": "online",
      "uri": "https://192.0.2.1/path"
    }
  ],
  "more_results": false
}

Retrieve an IP monitor

Request

GET /v1/ip_monitors/mon_sample123456

Response

On success, 200 with the IP monitor.

{
  "external_ref": null,
  "health": "online",
  "health_at": 1735689600,
  "host_ids": [
    "hst_sample123456"
  ],
  "hostname": "example.com",
  "id": "mon_sample123456",
  "in_use": true,
  "name": "Example",
  "nameserver_set_id": "nst_sample123456",
  "object": "ip_monitor",
  "treat_redirects": "online",
  "uri": "https://192.0.2.1/path"
}

Create an IP monitor

Request

POST /v1/ip_monitors

{
  "ip_monitor": {
    "name": "Example host",
    "nameserver_set_id": "nst_sample123456",
    "uri": "ping://192.0.2.2"
  }
}

Response

On success, 201 with the new IP monitor.
On error, 422 with standard error response.

{
  "external_ref": null,
  "health": "unknown",
  "health_at": 1735689600,
  "host_ids": [],
  "hostname": null,
  "id": "mon_sample123456",
  "in_use": false,
  "name": "Example host",
  "nameserver_set_id": "nst_sample123456",
  "object": "ip_monitor",
  "treat_redirects": "online",
  "uri": "ping://192.0.2.2"
}

Update an IP monitor

Request

PUT /v1/ip_monitors/mon_sample123456

{
  "ip_monitor": {
    "name": "Example"
  }
}

Response

On success, 200 with the updated IP monitor.
On error, 422 with standard error response.

{
  "external_ref": null,
  "health": "online",
  "health_at": 1735689600,
  "host_ids": [],
  "hostname": "example.com",
  "id": "mon_sample123456",
  "in_use": false,
  "name": "Example",
  "nameserver_set_id": "nst_sample123456",
  "object": "ip_monitor",
  "treat_redirects": "online",
  "uri": "https://192.0.2.1/path"
}

Delete an IP monitor

Request

DELETE /v1/ip_monitors/mon_sample123456

Response

On success, 202 with an empty response.
On error, 422 with standard error response.