About the Alerts API

API Version: 1.9

The Alerts API allows manage alerts saved to your NetworkCalc account.

Alert Type	Subtypes	Filters
`DNSRecord`	`A` `CNAME` `MX` `TXT`	`equals` `does notequal` `contains` `does not contain`
`SPFRecord`	No subtypes	`equals` `does notequal` `contains` `does not contain` `validity`
`Certificate(TLS)`	No subtypes	`subject` `expires in (days)`

Endpoints

https://networkcalc.com/api/alerts/{alert_id}

List one or more of the alerts saved to your account.

Example request and response

$ curl https://networkcalc.com/api/alerts/456 \
  --header "Authorization: Bearer 2jdS83kfDdDfllHk"

{
  "status": "OK",
  "alerts": [
    {
      "id": 456,
      "user_id": 1,
      "name": "Subdomain Alert - A Record Changed",
      "is_active": true,
      "current_status": "healthy",
      "type": "DNS Record",
      "subtype": "A",
      "filter": "does not equal",
      "filter_value": "198.51.100.57",
      "action": "email",
      "last_triggered_at": null,
      "target_domain": null,
      "target_subdomain": {
        "alert_id": 456,
        "subdomain_id": 123,
        "subdomain": {
          "id": 123,
          "prefix": "demo",
          "domain_id": 747,
          "domain_report": false,
          "domain": {
            "id": 747,
            "domain": "networkcalc.com",
            "report_schedule": null
          }
        }
      }
    }
  ]
}

This endpoint requires authorization. Read about API authorization or see NetworkCalc Pro pricing.

Parameters

{alert_id}

(Optional) The unique ID of the alert.

Example: https://networkcalc.com/api/alerts/12345

Response Format

AlertResponse

Response Codes

200

OK - Success.

400

MISSING_HEADER - A required header is missing.

401

NOT_AUTHORIZED - You do not have the necessary permissions.

400

MISSING_VALUES - One of the required parameters is missing from the body.

400

INVALID_BODY - One of the required parameters is invalid. Verify that the type, subtype, and filter are correct.

400

NOT_CREATED - The alert could not be saved. Verify the request and try again.

400

NOT_UPDATED - The alert could not be updated. Verify the request and try again.

400

NOT_DELETED - The alert could not be deleted. Verify the request and try again.

400

NOT_FOUND - A alert with the given ID could not be found.

Examples

Example 1

Run this in the API

cURL Example

curl -X GET https://networkcalc.com/api/alerts/456 \

--header "Authorization: Bearer 2jdS83kfDdDfllHk"

content_copy

PowerShell Example

$headers = @{"Authorization"="Bearer 2jdS83kfDdDfllHk"}

Invoke-RestMethod https://networkcalc.com/api/alerts/456 -Method GET -Headers $headers | ConvertTo-Json

content_copy

Python Example

import requests

headers = {"Authorization": "Bearer 2jdS83kfDdDfllHk"}

requests.get("https://networkcalc.com/api/alerts/456", headers = headers).json()

content_copy

Response

{

"status": "OK",

"alerts": [

{

"id": 456,

"user_id": 1,

"name": "Subdomain Alert - A Record Changed",

"is_active": true,

"current_status": "healthy",

"type": "DNS Record",

"subtype": "A",

"filter": "does not equal",

"filter_value": "198.51.100.57",

"action": "email",

"last_triggered_at": null,

"target_domain": null,

"target_subdomain": {

"alert_id": 456,

"subdomain_id": 123,

"subdomain": {

"id": 123,

"prefix": "demo",

"domain_id": 747,

"domain_report": false,

"domain": {

"id": 747,

"domain": "networkcalc.com",

"report_schedule": null

}

]

}

content_copy

https://networkcalc.com/api/alerts/

Save an alert to your account.

Example request and response

$ curl -X POST https://networkcalc.com/api/alerts \
  --header "Authorization: Bearer 2jdS83kfDdDfllHk" \
  --header "Content-Type: application/json" \
  --data '{
  "type": "DNS Record",
  "subtype": "A",
  "filter": "equals",
  "filter_value": "198.51.100.57",
  "target_type": "subdomain",
  "target_id": 123,
  "name": "Subdomain Alert - A Record Changed"
}'

{
  "status": "OK",
  "alert": {
    "alert_id": 456,
    "subdomain_id": 123
  }
}

This endpoint requires authorization. Read about API authorization or see NetworkCalc Pro pricing.

Parameters

{alert_id}

(Optional) The unique ID of the alert.

Example: https://networkcalc.com/api/alerts/12345

Request Headers

Content-Type

(Required) application/json

Request Body

{

"type": "[string] The type of alert. Must be one of: ['DNS Record', 'SPF Record', 'Certificate (TLS)'].",

"subtype": "[string] The subtype of the alert. See alert types for details.",

"filter": "[string] The filter for the alert. See alert types for details.",

"filter_value": "[string] The value that will trigger the alert if matched.",

"target_type": "[string] The type of resource the alert applies to. Must be one of: ['domain', 'subdomain'].",

"target_id": "[number] The unique identified for the target domain or subdomain (depending on target_type).",

"name": "[string] A display name for the alert."

}

content_copy

Response Format

AlertResponse

Response Codes

200

OK - Success.

400

MISSING_HEADER - A required header is missing.

401

NOT_AUTHORIZED - You do not have the necessary permissions.

400

MISSING_VALUES - One of the required parameters is missing from the body.

400

INVALID_BODY - One of the required parameters is invalid. Verify that the type, subtype, and filter are correct.

400

NOT_CREATED - The alert could not be saved. Verify the request and try again.

400

NOT_UPDATED - The alert could not be updated. Verify the request and try again.

400

NOT_DELETED - The alert could not be deleted. Verify the request and try again.

400

NOT_FOUND - A alert with the given ID could not be found.

Examples

Example 1

Run this in the API

cURL Example

curl -X POST https://networkcalc.com/api/alerts \

--header "Authorization: Bearer 2jdS83kfDdDfllHk" \

--header "Content-Type: application/json" \

--data '{ "type": "DNS Record", "subtype": "A", "filter": "equals", "filter_value": "198.51.100.57", "target_type": "subdomain", "target_id": 123, "name": "Subdomain Alert - A Record Changed" }'

content_copy

PowerShell Example

$headers = @{"Authorization"="Bearer 2jdS83kfDdDfllHk"; "Content-Type"="application/json"}

$body = @{"type"="DNS Record";"subtype"="A";"filter"="equals";"filter_value"="198.51.100.57";"target_type"="subdomain";"target_id"=123;"name"="Subdomain Alert - A Record Changed"} | ConvertTo-Json

Invoke-RestMethod https://networkcalc.com/api/alerts -Method POST -Body $body -Headers $headers | ConvertTo-Json

content_copy

Python Example

import requests

headers = {"Authorization": "Bearer 2jdS83kfDdDfllHk", "Content-Type": "application/json"}

data = { "type": "DNS Record", "subtype": "A", "filter": "equals", "filter_value": "198.51.100.57", "target_type": "subdomain", "target_id": 123, "name": "Subdomain Alert - A Record Changed" }

requests.post("https://networkcalc.com/api/alerts", json = data, headers = headers).json()

content_copy

Response

{

"status": "OK",

"alert": {

"alert_id": 456,

"subdomain_id": 123

}

content_copy

https://networkcalc.com/api/alerts/{alert_id}

Edit an alert in your account.

Example request and response

$ curl -X PATCH https://networkcalc.com/api/alerts/456 \
  --header "Authorization: Bearer 2jdS83kfDdDfllHk" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "My Updated Alert"
}'

{
  "status": "OK"
}

This endpoint requires authorization. Read about API authorization or see NetworkCalc Pro pricing.

Parameters

{alert_id}

(Optional) The unique ID of the alert.

Example: https://networkcalc.com/api/alerts/12345

Request Headers

Content-Type

(Required) application/json

Request Body

{

"type": "[string] The type of alert. Must be one of: ['DNS Record', 'SPF Record', 'Certificate (TLS)'].",

"subtype": "[string] The subtype of the alert. See alert types for details.",

"filter": "[string] The filter for the alert. See alert types for details.",

"filter_value": "[string] The value that will trigger the alert if matched.",

"target_type": "[string] The type of resource the alert applies to. Must be one of: ['domain', 'subdomain'].",

"target_id": "[number] The unique identified for the target domain or subdomain (depending on target_type).",

"name": "[string] A display name for the alert."

}

content_copy

Response Format

AlertUpdateResponse

Response Codes

200

OK - Success.

400

MISSING_HEADER - A required header is missing.

401

NOT_AUTHORIZED - You do not have the necessary permissions.

400

MISSING_VALUES - One of the required parameters is missing from the body.

400

INVALID_BODY - One of the required parameters is invalid. Verify that the type, subtype, and filter are correct.

400

NOT_CREATED - The alert could not be saved. Verify the request and try again.

400

NOT_UPDATED - The alert could not be updated. Verify the request and try again.

400

NOT_DELETED - The alert could not be deleted. Verify the request and try again.

400

NOT_FOUND - A alert with the given ID could not be found.

Examples

Example 1

Run this in the API

cURL Example

curl -X PATCH https://networkcalc.com/api/alerts/456 \

--header "Authorization: Bearer 2jdS83kfDdDfllHk" \

--header "Content-Type: application/json" \

--data '{ "name": "My Updated Alert" }'

content_copy

PowerShell Example

$headers = @{"Authorization"="Bearer 2jdS83kfDdDfllHk"; "Content-Type"="application/json"}

$body = @{"name"="My Updated Alert"} | ConvertTo-Json

Invoke-RestMethod https://networkcalc.com/api/alerts/456 -Method PATCH -Body $body -Headers $headers | ConvertTo-Json

content_copy

Python Example

import requests

headers = {"Authorization": "Bearer 2jdS83kfDdDfllHk", "Content-Type": "application/json"}

data = { "name": "My Updated Alert" }

requests.patch("https://networkcalc.com/api/alerts/456", json = data, headers = headers).json()

content_copy

Response

{

"status": "OK"

}

content_copy

https://networkcalc.com/api/alerts/{alert_id}

Delete an alert in your account.

Example request and response

$ curl -X DELETE https://networkcalc.com/api/alerts/456 \
  --header "Authorization: Bearer 2jdS83kfDdDfllHk"

{
  "status": "OK"
}

This endpoint requires authorization. Read about API authorization or see NetworkCalc Pro pricing.

Parameters

{alert_id}

(Optional) The unique ID of the alert.

Example: https://networkcalc.com/api/alerts/12345

Response Format

AlertDeleteResponse

Response Codes

200

OK - Success.

400

MISSING_HEADER - A required header is missing.

401

NOT_AUTHORIZED - You do not have the necessary permissions.

400

MISSING_VALUES - One of the required parameters is missing from the body.

400

INVALID_BODY - One of the required parameters is invalid. Verify that the type, subtype, and filter are correct.

400

NOT_CREATED - The alert could not be saved. Verify the request and try again.

400

NOT_UPDATED - The alert could not be updated. Verify the request and try again.

400

NOT_DELETED - The alert could not be deleted. Verify the request and try again.

400

NOT_FOUND - A alert with the given ID could not be found.

Examples

Example 1

Run this in the API

cURL Example

curl -X DELETE https://networkcalc.com/api/alerts/456 \

--header "Authorization: Bearer 2jdS83kfDdDfllHk"

content_copy

PowerShell Example

$headers = @{"Authorization"="Bearer 2jdS83kfDdDfllHk"}

Invoke-RestMethod https://networkcalc.com/api/alerts/456 -Method DELETE -Headers $headers | ConvertTo-Json

content_copy

Python Example

import requests

headers = {"Authorization": "Bearer 2jdS83kfDdDfllHk"}

requests.delete("https://networkcalc.com/api/alerts/456", headers = headers).json()

content_copy

Response

{

"status": "OK"

}

content_copy

Response Formats

{

"status": "[string] The status of the request.",

"alerts": "[array] An array of all alerts matching the request. See AlertResponse."

}

content_copy

{

"id": "[number] The alert's unique identifier.",

"user_id": "[number] The unique identifier for the user who created the alert.",

"name": "[string] A display name for the alert.",

"is_active": "[boolean] true if the alert is active and being checked, false otherwise.",

"current_status": "[string] The current status of the alert, e.g., healthy, triggered.",

"type": "[string] The type of alert.",

"subtype": "[string] The subtype of the alert.",

"filter": "[string] The filter applied when checking the alert's target resource.",

"filter_value": "[string] The value compared when checking the alert's target resource.",

"action": "[string] The response action if the alert is triggered. Currently, only email is supported.",

"last_triggered_at": "[timestamp] The date and time the alert was last triggered, or null if it has never been triggered/",

"target_domain": "[DomainResponse] If the alert's resource is a domain, the target domain. See Domain API",

"target_subdomain": "[DomainResponse] If the alert's resource is a subdomain, the target subdomain. See Domain API"

}

content_copy

{

"status": "[string] The status of the request.",

"error": "[string] An error message (if an error occurred)."

}

content_copy

{

"status": "[string] The status of the request."

}

content_copy