Home API Documentation Alerts API

Alerts API

About Endpoints List alerts Create an alert Edit an alert Delete an alert Response Formats

About the Alerts API

API Version: 1.9

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

Alert TypeSubtypesFilters
DNSRecord
  • A
  • CNAME
  • MX
  • TXT
  • equals
  • does notequal
  • contains
  • does not contain
SPFRecordNo subtypes
  • equals
  • does notequal
  • contains
  • does not contain
  • validity
Certificate(TLS)No subtypes
  • subject
  • expires in (days)

Endpoints

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

List alerts

. List one or more of the alerts saved to your account.
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 chevron_right

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
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
POST
https://networkcalc.com/api/alerts/
content_copy

Create an alert

. Save an alert to your account.
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 chevron_right

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
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
PATCH
https://networkcalc.com/api/alerts/{alert_id}
content_copy

Edit an alert

. Edit an alert in your account.
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 chevron_right

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
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
DELETE
https://networkcalc.com/api/alerts/
content_copy

Delete an alert

. Delete an alert in your account.
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 chevron_right

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
cURL Example
curl -X DELETE https://networkcalc.com/api/alert/456 \
--header "Authorization: Bearer 2jdS83kfDdDfllHk"
content_copy
PowerShell Example
$headers = @{"Authorization"="Bearer 2jdS83kfDdDfllHk"}
Invoke-RestMethod https://networkcalc.com/api/alert/456 -Method DELETE -Headers $headers | ConvertTo-Json
content_copy
Python Example
import requests
headers = {"Authorization": "Bearer 2jdS83kfDdDfllHk"}
requests.delete("https://networkcalc.com/api/alert/456", headers = headers).json()
content_copy
Response
{
  "status": "OK"
}
content_copy

Response Formats

AlertResponse

{
  "status": "[string] The status of the request.",
  "alerts": "[array] An array of all alerts matching the request. See AlertResponse."
}
content_copy

AlertResponse

{
  "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

AlertUpdateResponse

{
  "status": "[string] The status of the request.",
  "error": "[string] An error message (if an error occurred)."
}
content_copy

AlertDeleteResponse

{
  "status": "[string] The status of the request."
}
content_copy