How to Use the CleanTalk APIs for Website Uptime Monitoring

 

We offer our APIs for managing Website Uptime Monitoring. The interface is available here: cleantalk.org/my/?cp_mode=monitoring

Uptime Monitoring Guide:

 

Content:

General Information Website Uptime Monitoring APIs by CleanTalk

API monitoring_services_get Website Uptime Monitoring APIs by CleanTalk

API monitoring_services_add Website Uptime Monitoring APIs by CleanTalk

API monitoring_services_delete Website Uptime Monitoring APIs by CleanTalk

API monitoring_services_update Website Uptime Monitoring APIs by CleanTalk

General Information

Protocol - HTTPS

Hostname - api.cleantalk.org

API monitoring_services_get

Input Parameters

Transfer parameters via methods GET and POST.

 

Necessary

method_name allowed value: monitoring_services_get

user_token allowed values: you can get it in your dashboard in your CleanTalk control panel.

 

Example:

https://api.cleantalk.org/?method_name=monitoring_services_get&user_token=USER_TOKEN

 

Optional

start shift for the first record of the list, by default is 0

length limit of record quantity in the response, by default is 100, allowed values: 10, 25, 50, 100

order[0][dir] sorting direction of the records, allowed values: asc, desc

order[0][column] field index, records are being sorted by it

columns[0][data] field name of the record sorting, allowed values: monitor_id, URL, created, status, http_full_response_time, updown_duration, check_datetime

draw arbitrary value, will be sent in the response for the asynchronous requests.

 

Output Parameters

recordsTotal number of records without any filters

recordsFiltered number of records when filters are applied

draw arbitrary value, input parameters value

data monitor array:

  • monitor_id monitor ID
  • user_id user ID
  • URL website URL
  • created monitor creation time
  • check_datetime Date and time of the last website availability check
  • check_datetime Date and time of the last website availability check
  • checks_interval Interval in seconds between checks
  • down_datetime Date and time of the last website DOWN event
  • down_duration Duration in seconds of the last DOWN event
  • down_events_count_7d Number of DOWN events in the previous 7 days
  • down_events_losses_7d Number of seconds of inactivity (DOWN event) for the previous 7 days
  • email_notification_delay Delay in seconds before sending notification
  • email_notification_sent Date and time of the last notification
  • email_notification_status_sent Website status at the time of previous notification
  • http_full_response_time Time in seconds of the full website load: DNS query + site access + HTML content downloading
  • http_full_response_time_avg_1d Average response time in seconds last 24 hours ago
  • http_full_response_time_avg_7d Average response time in seconds last 7 days ago
  • http_full_response_time_progress Dynamics of the average URL response time for the previous 24 hours relative to 7 days ago
  • http_method Check method: HEAD — is the most optimal way of checking the website availability, it doesn't create any unwanted load, but doesn't show site errors either. GET — the website page will be fully loaded with this option. It can load the website if there is a large number of requests. It is recommended to be used only in cases when you need to find out what type of error the site gives.
  • status Current validation status. ACTIVE - validation is running, PAUSE - validation is stopped
  • updown_datetime Date and time of the current state
  • updown_duration Duration in seconds of the current state
  • updown_http_status Current state

 

Example:

https://api.cleantalk.org/?method_name=monitoring_services_get&user_token=USER_TOKEN&draw=10&columns[0][data]=monitor_id&columns[1][data]=URL&columns[2][data]=status&columns[3][data]=created&order[0][column]=3&order[0][dir]=asc&start=0&length=10
{"data":[{"monitor_id":"4826","user_id":"253332","created":"2020-11-17 10:29:05","URL":"http:\/\/example.com\/","status":"ACTIVE","monitoring_type":"HTTP","check_datetime":"2020-11-17 10:29:24","http_full_response_time":"0.068","http_status":"1","email_notification_sent":null,"email_notification_status_sent":null,"updown_http_status":"UP","updown_datetime":"2020-11-17 10:29:24","updown_duration":"5","down_datetime":null,"down_duration":null,"http_full_response_time_progress":null,"http_full_response_time_avg_1d":null,"http_full_response_time_avg_7d":null,"down_events_count_7d":null,"down_events_losses_7d":null,"http_method":"HEAD","checks_interval":"180","email_notification_delay":"60"}],"draw":"4","recordsTotal":"1","recordsFiltered":"1","currentPage":0}

 

Possible Errors

https://api.cleantalk.org/?method_name=monitoring_services_get
{"data":{"result":"FAIL","notice":"User token not found","operation_code":"51"}}

 

API monitoring_services_add

Input Parameters

 

Necessary

method_name allowed value: monitoring_services_add

user_token allowed value: you can get it in your dashboard in your CleanTalk control panel.

URL website valid URL

  • Data array, example: URL[]=example.com&URL[]=example1.com
  • String, comma as a separator, example: URL=example.com,example1.com

 

Example:

https://api.cleantalk.org/?method_name=monitoring_services_add&user_token=USER_TOKEN&URL=example.com
{"data":{"monitors":[{"monitor_id":4830,"operation_status":"SUCCESS"}]}}

 

Optional

http_method Checking method, allowed values: HEAD (default value), GET 

checks_interval How often the check will be performed, allowed values: 60,120,180 (default value),120,300,600,900,1800,3600

email_notification_delay How quickly the notification will be sent, allowed values: 0 (default value),60,300,900,1800,3600

 

Output Parameters

monitors monitor array:

  • monitor_id monitor ID
  • operation_status operation status

 

Example:

https://api.cleantalk.org/?method_name=monitoring_services_add&user_token=USER_TOKEN&URL=example.com&http_method=HEAD&checks_interval=180&email_notification_delay=60
{"data":{"monitors":[{"monitor_id":4830,"operation_status":"SUCCESS"}]}}

 

Possible Errors

https://api.cleantalk.org/?method_name=monitoring_services_add
{"data":{"result":"FAIL","notice":"User token not found","operation_code":"51"}}

 

https://api.cleantalk.org/?method_name=monitoring_services_add&user_token=USER_TOKEN
{"error_message":"URL is required","error_no":"1"}

 

https://api.cleantalk.org/?method_name=monitoring_services_add&user_token=USER_TOKEN&URL=example.com&http_method=POST
{"error_message":"http_method must be in HEAD or GET","error_no":"48"}

 

https://api.cleantalk.org/?method_name=monitoring_services_add&user_token=USER_TOKEN&URL=example.com&checks_interval=1
{"error_message":"checks_interval must be in (60,120,180,120,300,600,900,1800,3600)","error_no":"49"}

 

https://api.cleantalk.org/?method_name=monitoring_services_add&user_token=USER_TOKEN&URL=example.com&email_notification_delay=1
{"error_message":"email_notification_delay must be in (0,60,300,900,1800,3600)","error_no":"401"}

 

https://api.cleantalk.org/?method_name=monitoring_services_add&user_token=USER_TOKEN&URL=example.com
{"data":{"monitors":[{"URL":"http:\/\/example.com\/","operation_status":"FAILED","operation_message":"URL already exists","operation_code":"6"}]}}

 

https://api.cleantalk.org/?method_name=monitoring_services_add&user_token=USER_TOKEN&URL=example.com
{"data":{"monitors":[{"URL":"http:\/\/example.com","operation_status":"FAILED","operation_message":"License limit exceeded","operation_code":"7"}]}}

 

API monitoring_services_delete

Input Parameters

method_name allowed value: monitoring_services_delete

user_token allowed values: you can get it in your dashboard in your CleanTalk control panel.

monitorig_ids

  • Data array, example: monitorig_ids[]=3985411&monitorig_ids[]=3985397
  • String, comma as a separator, example: monitorig_ids=3985411,3985397

Output Parameters

monitors monitor array:

  • monitor_id monitor ID
  • operation_status operation status

 

Example:

https://api.cleantalk.org/?method_name=monitoring_services_delete&user_token=USER_TOKEN&record_ids=4830
{"data":{"monitors":[{"monitor_id":"4830","operation_status":"SUCCESS"}]}}

 

Possible Errors

https://api.cleantalk.org/?method_name=monitoring_services_delete&user_token=USER_TOKEN
{"error_message":"monitor_ids is required","error_no":"22"}
https://api.cleantalk.org/?method_name=monitoring_services_delete&user_token=USER_TOKEN&monitor_ids=4830,4831
{"data":{"monitors":[{"monitor_id":"4830","operation_status":"FAILED","operation_message":"Monitor not found","operation_code":"21"},{"monitor_id":"4831","operation_status":"FAILED","operation_message":"Monitor not found","operation_code":"21"}]}}

 

API monitoring_services_update

Input Parameters

method_name allowed value: monitoring_services_update

user_token allowed values: you can get it in your dashboard in your CleanTalk control panel.

monitorig_ids

  • Data array, example: monitorig_ids[]=3985411&monitorig_ids[]=3985397
  • String, comma as a separator, example: monitorig_ids=3985411,3985397

URL allowed values: valid URL

status allowed values: ACTIVE or PAUSE

http_method allowed values: HEAD or GET

checks_interval allowed values: 60,120,180,120,300,600,900,1800,3600

email_notification_delay allowed values: 0,60,300,900,1800,3600

 

Output Parameters

monitors monitor array:

  • monitor_id monitor ID
  • operation_status operation status

 

Example:

https://api.cleantalk.org/?method_name=monitoring_services_update&user_token=USER_TOKEN&monitor_ids=4846,4848&status=PAUSE
{"data":{"monitors":[{"monitor_id":4846,"operation_status":"SUCCESS"},{"monitor_id":4848,"operation_status":"SUCCESS"}]}}

 

Possible Errors

https://api.cleantalk.org/?method_name=monitoring_services_update&user_token=USER_TOKEN
{"data":{"error_message":"monitor_ids is required","error_no":"41"}}
https://api.cleantalk.org/?method_name=monitoring_services_update&user_token=USER_TOKEN&monitor_ids=4847,4849&status=PAUSE
{"data":{"monitors":[{"monitor_id":"4847","operation_status":"FAILED","operation_message":"Monitor not found","operation_code":"44"},{"monitor_id":"4849","operation_status":"FAILED","operation_message":"Monitor not found","operation_code":"44"}]}}
https://api.cleantalk.org/?method_name=monitoring_services_update&user_token=USER_TOKEN&monitor_ids=4846,4848&status=TEST
{"error_message":"status must be in ACTIVE or PAUSE","error_no":"47"}
https://api.cleantalk.org/?method_name=monitoring_services_update&user_token=USER_TOKEN&monitor_ids=4846,4848&http_method=TEST
{"error_message":"http_method must be in HEAD or GET","error_no":"48"}
https://api.cleantalk.org/?method_name=monitoring_services_update&user_token=USER_TOKEN&monitor_ids=4846,4848&checks_interval=TEST
{"error_message":"checks_interval must be in (60,120,180,120,300,600,900,1800,3600)","error_no":"49"}
https://api.cleantalk.org/?method_name=monitoring_services_update&user_token=USER_TOKEN&monitor_ids=4846,4848&email_notification_delay=5
{"error_message":"email_notification_delay must be in (0,60,300,900,1800,3600)","error_no":"401"}

 

 

 


Perhaps it would also be interesting