POST/v1/checks/tcp
Create a TCP check
Create a new TCP check to monitor TCP connectivity
Requires UPTIME_CHECKS:EDIT.
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: "TCP_CHECK"
tcp_hostname:string
Publicly reachable hostname or IP address to connect to
tcp_port:integer
TCP port to connect to
tcp_ip_family:stringoptional
IP family to use for DNS resolution and socket connection
Accepted values: "IPv4" | "IPv6"
Default: "IPv4"
tcp_data:string | nulloptional
Optional TCP payload to send immediately after connecting
tcp_should_fail:booleanoptional
Whether a failed TCP connection should be treated as passing
Default: false
assertions:object[]optional
TCP assertions to run on response time or response data
Responses
| Status | Meaning | Description |
|---|---|---|
| 201 | Created | Create a new OnlineOrNot TCP Check |
| 400 | Bad Request | Validation error |
| 401 | Unauthorized | Unauthenticated |
| 403 | Forbidden | Forbidden |
| 500 | Internal Server Error | Internal Server Error |
Response Schema
result:object
success:boolean
Whether the API call was successful
errors:object[]
messages:object[]
Request
POST
/v1/checks/tcpcurl --request POST \
--url https://api.onlineornot.com/v1/checks/tcp \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"TCP for example.com:443","tcp_hostname":"example.com","tcp_port":443,"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": "TCP",
"url": null,
"version": "NODE24_TCP",
"tcp_hostname": "tcpbin.com",
"tcp_port": 4242,
"tcp_ip_family": "IPv4",
"tcp_data": "string",
"tcp_should_fail": false,
"assertions": [
{
"type": "TCP_RESPONSE_DATA",
"property": "",
"comparison": "EQUALS",
"expected": "OK"
}
]
},
"success": true,
"errors": [],
"messages": []
}
GET/v1/checks/tcp/{check_id}
Retrieve a TCP check
Look up detailed information about a specific TCP check
Requires UPTIME_CHECKS:READ.
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
| Status | Meaning | Description |
|---|---|---|
| 200 | OK | Retrieve the specified OnlineOrNot TCP Check. May also return a canonical failure envelope with success: false at HTTP200. |
| 400 | Bad Request | Invalid request |
| 401 | Unauthorized | Unauthenticated |
| 403 | Forbidden | Forbidden |
| 404 | Not Found | TCP check not found |
| 500 | Internal Server Error | Internal Server Error |
Response Schema
success:boolean
false
result:null
errors:object[]
messages:[any]
Request
GET
/v1/checks/tcp/{check_id}curl --request GET \
--url https://api.onlineornot.com/v1/checks/tcp/a1b2c3d4 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
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": "TCP",
"url": null,
"version": "NODE24_TCP",
"tcp_hostname": "tcpbin.com",
"tcp_port": 4242,
"tcp_ip_family": "IPv4",
"tcp_data": "string",
"tcp_should_fail": false,
"assertions": [
{
"type": "TCP_RESPONSE_DATA",
"property": "",
"comparison": "EQUALS",
"expected": "OK"
}
]
},
"success": true,
"errors": [],
"messages": []
}
PATCH/v1/checks/tcp/{check_id}
Modify a TCP check
Modify the configuration of an existing TCP check
Requires UPTIME_CHECKS:EDIT.
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.
tcp_hostname:stringoptional
Publicly reachable hostname or IP address to connect to
tcp_port:integeroptional
TCP port to connect to
tcp_ip_family:stringoptional
Accepted values: "IPv4" | "IPv6"
tcp_data:string | nulloptional
Optional TCP payload to send immediately after connecting
tcp_should_fail:booleanoptional
assertions:object[]optional
Responses
| Status | Meaning | Description |
|---|---|---|
| 200 | OK | Modify an OnlineOrNot TCP Check |
| 400 | Bad Request | Validation error |
| 401 | Unauthorized | Unauthenticated |
| 403 | Forbidden | Forbidden |
| 404 | Not Found | TCP check not found |
| 500 | Internal Server Error | Internal Server Error |
Response Schema
result:object
success:boolean
Whether the API call was successful
errors:object[]
messages:object[]
Request
PATCH
/v1/checks/tcp/{check_id}curl --request PATCH \
--url https://api.onlineornot.com/v1/checks/tcp/a1b2c3d4 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"tcp_hostname":"example.org","tcp_port":8443,"tcp_ip_family":"IPv4"}'
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": "TCP",
"url": null,
"version": "NODE24_TCP",
"tcp_hostname": "tcpbin.com",
"tcp_port": 4242,
"tcp_ip_family": "IPv4",
"tcp_data": "string",
"tcp_should_fail": false,
"assertions": [
{
"type": "TCP_RESPONSE_DATA",
"property": "",
"comparison": "EQUALS",
"expected": "OK"
}
]
},
"success": true,
"errors": [],
"messages": []
}
DELETE/v1/checks/tcp/{check_id}
Delete a TCP check
Permanently delete a TCP check
Requires UPTIME_CHECKS:EDIT.
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
| Status | Meaning | Description |
|---|---|---|
| 200 | OK | Returns the deleted OnlineOrNot TCP Check's ID |
| 400 | Bad Request | Validation error |
| 401 | Unauthorized | Unauthenticated |
| 403 | Forbidden | Forbidden |
| 404 | Not Found | TCP check not found |
| 500 | Internal Server Error | Internal Server Error |
Response Schema
result:object
success:boolean
Whether the API call was successful
errors:object[]
messages:object[]
Request
DELETE
/v1/checks/tcp/{check_id}curl --request DELETE \
--url https://api.onlineornot.com/v1/checks/tcp/a1b2c3d4 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
Response
{
"result": {
"id": "a1b2c3d4"
},
"success": true,
"errors": [],
"messages": []
}
GET/v1/checks/tcp/{check_id}/incidents
Review recent failures and recoveries for a specific TCP check
List incidents for a TCP check. Use from and to to include incidents that overlap the time range. Results are sorted by start time, then ID, newest first. Timestamps accept up to three decimal places for seconds. Pagination accepts safe integers, including the calculated offset. The per_page limit is 100.
Requires UPTIME_CHECKS:READ.
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
| Status | Meaning | Description |
|---|---|---|
| 200 | OK | A page of incidents for the check |
| 400 | Bad Request | Invalid query parameters |
| 401 | Unauthorized | Unauthenticated |
| 403 | Forbidden | Forbidden |
| 404 | Not Found | Check not found |
| 500 | Internal Server Error | Internal server error |
Response Schema
success:boolean
true
result:object[]
result_info:object
errors:array
messages:array
Request
GET
/v1/checks/tcp/{check_id}/incidentscurl --request GET \
--url https://api.onlineornot.com/v1/checks/tcp/a1b2c3d4/incidents \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
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/tcp/{check_id}/results
Review raw TCP check results over a bounded time range
List results for a TCP check. Set to later than from. The time range cannot exceed seven days. Timestamps accept up to three decimal places for seconds. Use positive safe integers for page and per_page. The calculated offset must also be a safe integer. The per_page limit is 100.
Requires UPTIME_CHECKS:READ.
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
| Status | Meaning | Description |
|---|---|---|
| 200 | OK | A chronological page of raw check results |
| 400 | Bad Request | Invalid query parameters |
| 401 | Unauthorized | Unauthenticated |
| 403 | Forbidden | Forbidden |
| 404 | Not Found | Check not found |
| 500 | Internal Server Error | Internal server error |
| 503 | Service Unavailable | Required result storage unavailable |
Response Schema
success:boolean
true
result:object
errors:array
messages:array
Request
GET
/v1/checks/tcp/{check_id}/resultscurl --request GET \
--url 'https://api.onlineornot.com/v1/checks/tcp/a1b2c3d4/results?from=2026-08-25T10%3A00%3A00Z&to=2026-08-25T11%3A00%3A00Z' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
Response
{
"success": true,
"result": {
"check_id": "string",
"check_type": "TCP",
"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",
"tcp_status": "string",
"failure_source": "TRANSPORT",
"failure_type": "string",
"dns_time_ms": 0,
"connect_time_ms": 0,
"data_time_ms": 0
}
],
"result_info": {
"page": 0,
"per_page": 1,
"count": 0,
"total_count": 0
}
},
"errors": [
null
],
"messages": [
null
]
}