POST/v1/checks/dns

Create a DNS check

Create a new DNS check to monitor DNS records

Requires UPTIME_CHECKS:EDIT; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Body parameters

name:string
test_interval:integeroptional
Interval in seconds between checks
test_regions:string[]optional
Regions to run checks from. Valid regions: aws:us-east-1, aws:us-east-2, aws:us-west-1, aws:eu-central-1, aws:eu-west-2, aws:ap-south-1, aws:ap-southeast-2, aws:ap-northeast-1
user_alerts:string[]optional
slack_alerts:string[]optional
discord_alerts:string[]optional
incident_io_alerts:string[]optional
microsoft_teams_alerts:string[]optional
telegram_alerts:string[]optional
pushover_alerts:string[]optional
webhook_alerts:string[]optional
IDs of webhooks to associate with this check
oncall_alerts:string[]optional
IDs of on-call integrations (Grafana, PagerDuty, Opsgenie, Spike)
alert_priority:stringoptional
[Alert priority](https://onlineornot.com/docs/how-to/alerts/configure-priority).
Accepted values: "LOW" | "HIGH"
Default: "HIGH"
confirmation_period_seconds:integeroptional
Seconds before confirming [downtime](https://onlineornot.com/docs/explanation/confirmation-recovery-periods#confirmation-period).
Default: 60
recovery_period_seconds:integeroptional
Seconds before confirming [recovery](https://onlineornot.com/docs/explanation/confirmation-recovery-periods#recovery-period).
Default: 180
reminder_alert_interval_minutes:integeroptional
Interval in minutes between reminders (-1 for never)
Default: 1440
timeout:integeroptional
Timeout in milliseconds
Default: 10000
type:stringoptional
Accepted values: "DNS_CHECK"
dns_domain:string
DNS name to query
dns_record_type:string
DNS record type to query
Accepted values: "A" | "AAAA" | "CNAME" | "MX" | "NS" | "SOA" | "TXT"
dns_resolver:stringnulloptional
Custom DNS resolver in host:port format. IPv6 must use bracket notation.
dns_protocol:stringoptional
DNS transport protocol
Accepted values: "UDP" | "TCP"
Default: "UDP"
assertions:object[]optional
DNS assertions to run on the response

Responses

StatusMeaningDescription
201CreatedCreate a new OnlineOrNot DNS Check
400Bad RequestValidation error
401UnauthorizedUnauthenticated
403ForbiddenForbidden
500Internal Server ErrorInternal Server Error

Response Schema

result:object
success:boolean
Whether the API call was successful
errors:object[]
messages:object[]

Request

POST
/v1/checks/dns
curl --request POST \
  --url https://api.onlineornot.com/v1/checks/dns \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --header 'X-OnlineOrNot-Organisation: string' \
  --data '{"name":"DNS for example.com","dns_domain":"example.com","dns_record_type":"A","test_interval":60}'

Response

{
  "result": {
    "id": "a1b2c3d4",
    "name": "My landing page",
    "last_queued": "2021-01-01T00:00:00.000Z",
    "status": "UP",
    "reminder_alert_interval_minutes": 1440,
    "confirmation_period_seconds": 60,
    "recovery_period_seconds": 180,
    "test_interval": 60,
    "timeout": 0,
    "alert_priority": "HIGH",
    "test_regions": [
      "aws:us-east-1",
      "aws:eu-central-1"
    ],
    "user_alerts": [
      "string"
    ],
    "slack_alerts": [
      "string"
    ],
    "discord_alerts": [
      "string"
    ],
    "incident_io_alerts": [
      "string"
    ],
    "microsoft_teams_alerts": [
      "string"
    ],
    "telegram_alerts": [
      "string"
    ],
    "pushover_alerts": [
      "string"
    ],
    "oncall_alerts": [
      "string"
    ],
    "webhook_alerts": [
      "string"
    ],
    "check_type": "DNS",
    "url": null,
    "version": "NODE24_DNS",
    "dns_domain": "example.com",
    "dns_record_type": "A",
    "dns_resolver": "8.8.8.8:53",
    "dns_protocol": "UDP",
    "assertions": [
      {
        "type": "DNS_JSON_ANSWER",
        "property": "$.answers[0].data",
        "comparison": "EQUALS",
        "expected": "93.184.216.34"
      }
    ]
  },
  "success": true,
  "errors": [],
  "messages": []
}
GET/v1/checks/dns/{check_id}

Retrieve a DNS check

Look up detailed information about a specific DNS check

Requires UPTIME_CHECKS:READ; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Path parameters

check_id:string
Uptime Check ID

Responses

StatusMeaningDescription
200OKRetrieve the specified OnlineOrNot DNS Check. May also return a canonical failure envelope with success: false at HTTP200.
400Bad RequestInvalid request
401UnauthorizedUnauthenticated
403ForbiddenForbidden
404Not FoundDNS check not found
500Internal Server ErrorInternal Server Error

Response Schema

success:boolean
false
result:null
errors:object[]
messages:[any]

Request

GET
/v1/checks/dns/{check_id}
curl --request GET \
  --url https://api.onlineornot.com/v1/checks/dns/a1b2c3d4 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'X-OnlineOrNot-Organisation: string'

Response

{
  "result": {
    "id": "a1b2c3d4",
    "name": "My landing page",
    "last_queued": "2021-01-01T00:00:00.000Z",
    "status": "UP",
    "reminder_alert_interval_minutes": 1440,
    "confirmation_period_seconds": 60,
    "recovery_period_seconds": 180,
    "test_interval": 60,
    "timeout": 0,
    "alert_priority": "HIGH",
    "test_regions": [
      "aws:us-east-1",
      "aws:eu-central-1"
    ],
    "user_alerts": [
      "string"
    ],
    "slack_alerts": [
      "string"
    ],
    "discord_alerts": [
      "string"
    ],
    "incident_io_alerts": [
      "string"
    ],
    "microsoft_teams_alerts": [
      "string"
    ],
    "telegram_alerts": [
      "string"
    ],
    "pushover_alerts": [
      "string"
    ],
    "oncall_alerts": [
      "string"
    ],
    "webhook_alerts": [
      "string"
    ],
    "check_type": "DNS",
    "url": null,
    "version": "NODE24_DNS",
    "dns_domain": "example.com",
    "dns_record_type": "A",
    "dns_resolver": "8.8.8.8:53",
    "dns_protocol": "UDP",
    "assertions": [
      {
        "type": "DNS_JSON_ANSWER",
        "property": "$.answers[0].data",
        "comparison": "EQUALS",
        "expected": "93.184.216.34"
      }
    ]
  },
  "success": true,
  "errors": [],
  "messages": []
}
PATCH/v1/checks/dns/{check_id}

Modify a DNS check

Modify the configuration of an existing DNS check

Requires UPTIME_CHECKS:EDIT; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Path parameters

check_id:string
Uptime Check ID

Body parameters

name:stringoptional
test_interval:integeroptional
Interval in seconds between checks
test_regions:string[]optional
Regions to run checks from. Valid regions: aws:us-east-1, aws:us-east-2, aws:us-west-1, aws:eu-central-1, aws:eu-west-2, aws:ap-south-1, aws:ap-southeast-2, aws:ap-northeast-1
user_alerts:string[]optional
slack_alerts:string[]optional
discord_alerts:string[]optional
incident_io_alerts:string[]optional
microsoft_teams_alerts:string[]optional
telegram_alerts:string[]optional
pushover_alerts:string[]optional
webhook_alerts:string[]optional
IDs of webhooks to associate with this check
oncall_alerts:string[]optional
IDs of on-call integrations (Grafana, PagerDuty, Opsgenie, Spike)
alert_priority:stringoptional
[Alert priority](https://onlineornot.com/docs/how-to/alerts/configure-priority).
Accepted values: "LOW" | "HIGH"
Default: "HIGH"
confirmation_period_seconds:integeroptional
Seconds before confirming [downtime](https://onlineornot.com/docs/explanation/confirmation-recovery-periods#confirmation-period).
recovery_period_seconds:integeroptional
Seconds before confirming [recovery](https://onlineornot.com/docs/explanation/confirmation-recovery-periods#recovery-period).
reminder_alert_interval_minutes:integeroptional
Interval in minutes between reminders (-1 for never)
timeout:integeroptional
Timeout in milliseconds
paused:booleanoptional
Stops check execution when true.
muted:booleanoptional
Suppresses alerts without stopping checks.
dns_domain:stringoptional
dns_record_type:stringoptional
Accepted values: "A" | "AAAA" | "CNAME" | "MX" | "NS" | "SOA" | "TXT"
dns_resolver:stringnulloptional
Custom DNS resolver in host:port format. IPv6 must use bracket notation.
dns_protocol:stringoptional
Accepted values: "UDP" | "TCP"
assertions:object[]optional

Responses

StatusMeaningDescription
200OKModify an OnlineOrNot DNS Check
400Bad RequestValidation error
401UnauthorizedUnauthenticated
403ForbiddenForbidden
404Not FoundDNS check not found
500Internal Server ErrorInternal Server Error

Response Schema

result:object
success:boolean
Whether the API call was successful
errors:object[]
messages:object[]

Request

PATCH
/v1/checks/dns/{check_id}
curl --request PATCH \
  --url https://api.onlineornot.com/v1/checks/dns/a1b2c3d4 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --header 'X-OnlineOrNot-Organisation: string' \
  --data '{"dns_domain":"example.org","dns_record_type":"TXT","dns_resolver":"1.1.1.1:53","dns_protocol":"TCP"}'

Response

{
  "result": {
    "id": "a1b2c3d4",
    "name": "My landing page",
    "last_queued": "2021-01-01T00:00:00.000Z",
    "status": "UP",
    "reminder_alert_interval_minutes": 1440,
    "confirmation_period_seconds": 60,
    "recovery_period_seconds": 180,
    "test_interval": 60,
    "timeout": 0,
    "alert_priority": "HIGH",
    "test_regions": [
      "aws:us-east-1",
      "aws:eu-central-1"
    ],
    "user_alerts": [
      "string"
    ],
    "slack_alerts": [
      "string"
    ],
    "discord_alerts": [
      "string"
    ],
    "incident_io_alerts": [
      "string"
    ],
    "microsoft_teams_alerts": [
      "string"
    ],
    "telegram_alerts": [
      "string"
    ],
    "pushover_alerts": [
      "string"
    ],
    "oncall_alerts": [
      "string"
    ],
    "webhook_alerts": [
      "string"
    ],
    "check_type": "DNS",
    "url": null,
    "version": "NODE24_DNS",
    "dns_domain": "example.com",
    "dns_record_type": "A",
    "dns_resolver": "8.8.8.8:53",
    "dns_protocol": "UDP",
    "assertions": [
      {
        "type": "DNS_JSON_ANSWER",
        "property": "$.answers[0].data",
        "comparison": "EQUALS",
        "expected": "93.184.216.34"
      }
    ]
  },
  "success": true,
  "errors": [],
  "messages": []
}
DELETE/v1/checks/dns/{check_id}

Delete a DNS check

Permanently delete a DNS check

Requires UPTIME_CHECKS:EDIT; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Path parameters

check_id:string
Uptime Check ID

Responses

StatusMeaningDescription
200OKReturns the deleted OnlineOrNot DNS Check's ID
400Bad RequestValidation error
401UnauthorizedUnauthenticated
403ForbiddenForbidden
404Not FoundDNS check not found
500Internal Server ErrorInternal Server Error

Response Schema

result:object
success:boolean
Whether the API call was successful
errors:object[]
messages:object[]

Request

DELETE
/v1/checks/dns/{check_id}
curl --request DELETE \
  --url https://api.onlineornot.com/v1/checks/dns/a1b2c3d4 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'X-OnlineOrNot-Organisation: string'

Response

{
  "result": {
    "id": "a1b2c3d4"
  },
  "success": true,
  "errors": [],
  "messages": []
}
GET/v1/checks/dns/{check_id}/incidents

Review recent failures and recoveries for a specific DNS check

List incidents for a DNS check. Optional from/to select overlapping incidents, not only incidents starting within the interval. Results are ordered by started time descending, then ID descending. Bounds accept at most millisecond precision; page/per_page and the computed offset must be safe integers, with per_page <= 100.

Requires UPTIME_CHECKS:READ; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Path parameters

check_id:string
Public check ID

Query parameters

page:integeroptional
Page number of paginated results
Default: 1
per_page:integeroptional
Number of records per page, from 1 through 100
Default: 20
from:string(date-time)optional
Inclusive start of the requested time range
to:string(date-time)optional
Exclusive end of the requested time range. Must be later than from when both are provided.

Responses

StatusMeaningDescription
200OKA page of incidents for the check
400Bad RequestInvalid query parameters
401UnauthorizedUnauthenticated
403ForbiddenForbidden
404Not FoundCheck not found
500Internal Server ErrorInternal server error

Response Schema

success:boolean
true
result:object[]
result_info:object
errors:array
messages:array

Request

GET
/v1/checks/dns/{check_id}/incidents
curl --request GET \
  --url https://api.onlineornot.com/v1/checks/dns/a1b2c3d4/incidents \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'X-OnlineOrNot-Organisation: string'

Response

{
  "success": true,
  "result": [
    {
      "id": "string",
      "check_id": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "ended_at": "2019-08-24T14:15:22Z"
    }
  ],
  "result_info": {
    "page": 0,
    "per_page": 1,
    "count": 0,
    "total_count": 0
  },
  "errors": [
    null
  ],
  "messages": [
    null
  ]
}
GET/v1/checks/dns/{check_id}/results

Review raw DNS check results over a bounded time range

List results for a DNS check. Requires from < to, at most seven days, and at most three fractional timestamp digits. Pagination uses positive safe integers with per_page <= 100 and a safe integer offset.

Requires UPTIME_CHECKS:READ; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Path parameters

check_id:string
Public check ID

Query parameters

page:integeroptional
Page number of paginated results
Default: 1
per_page:integeroptional
Number of records per page, from 1 through 100
Default: 20
from:string(date-time)
Inclusive start of the requested time range
to:string(date-time)
Exclusive end of the requested time range

Responses

StatusMeaningDescription
200OKA chronological page of raw check results
400Bad RequestInvalid query parameters
401UnauthorizedUnauthenticated
403ForbiddenForbidden
404Not FoundCheck not found
500Internal Server ErrorInternal server error
503Service UnavailableRequired result storage unavailable

Response Schema

success:boolean
true
result:object
errors:array
messages:array

Request

GET
/v1/checks/dns/{check_id}/results
curl --request GET \
  --url 'https://api.onlineornot.com/v1/checks/dns/a1b2c3d4/results?from=2026-08-25T10%3A00%3A00Z&to=2026-08-25T11%3A00%3A00Z' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'X-OnlineOrNot-Organisation: string'

Response

{
  "success": true,
  "result": {
    "check_id": "string",
    "check_type": "DNS",
    "window": {
      "from": "2019-08-24T14:15:22Z",
      "to": "2019-08-24T14:15:22Z"
    },
    "results": [
      {
        "id": "string",
        "checked_at": "2019-08-24T14:15:22Z",
        "checked_from": "aws:us-east-1",
        "passing": true,
        "response_time_ms": 0,
        "attempt_number": 0,
        "is_final_attempt": true,
        "dispatched_at_ms": 0,
        "response_body": "string",
        "body_availability": "AVAILABLE",
        "dns_status": "string",
        "failure_source": "TRANSPORT",
        "failure_type": "string",
        "resolver": "string",
        "parsed_response": "string"
      }
    ],
    "result_info": {
      "page": 0,
      "per_page": 1,
      "count": 0,
      "total_count": 0
    }
  },
  "errors": [
    null
  ],
  "messages": [
    null
  ]
}

Was this page helpful?