Create an HTTP, TCP port or ping monitor.
const url = 'https://api.siteqwality.com/v1/http-monitors';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"service_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","check_regions":["example"],"min_healthy_regions":1,"friendly_name":"example","follow_redirects":true,"final_uri":"example","check_type":"http","method":"example","keyword_search":"example","keyword_search_inverted":true,"keyword_search_case_sensitive":true,"keyword_search_regex":true,"timeout_ms":1,"uri":"example","tcp_send":"example","tcp_expect":"example","tcp_tls":true,"ping_count":1,"ping_loss_threshold":1,"recheck_on_failure":"off","web_bot_auth":true,"request_body":"example","content_type":"json","auth_type":"basic","auth_username":"example","auth_password":"example","auth_bearer_token":"example","success_http_codes":[1],"failure_http_codes":[1],"custom_http_headers":"example","run_interval_seconds":1,"run_interval_thirty_seconds":true,"group_notification_ids":["2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"],"monitor_tls":true,"monitor_dns":true,"monitor_page_speed":true,"tags":["example"],"http_version":"auto","confirmation_threshold":1,"json_path":"example","json_path_expected":"example","tls_port":1,"alert_on_invalid_certificate":true,"recovery_period_runs":1,"flap_hold":true,"flap_hold_override":true,"trace_propagation":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.siteqwality.com/v1/http-monitors \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "service_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "check_regions": [ "example" ], "min_healthy_regions": 1, "friendly_name": "example", "follow_redirects": true, "final_uri": "example", "check_type": "http", "method": "example", "keyword_search": "example", "keyword_search_inverted": true, "keyword_search_case_sensitive": true, "keyword_search_regex": true, "timeout_ms": 1, "uri": "example", "tcp_send": "example", "tcp_expect": "example", "tcp_tls": true, "ping_count": 1, "ping_loss_threshold": 1, "recheck_on_failure": "off", "web_bot_auth": true, "request_body": "example", "content_type": "json", "auth_type": "basic", "auth_username": "example", "auth_password": "example", "auth_bearer_token": "example", "success_http_codes": [ 1 ], "failure_http_codes": [ 1 ], "custom_http_headers": "example", "run_interval_seconds": 1, "run_interval_thirty_seconds": true, "group_notification_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "monitor_tls": true, "monitor_dns": true, "monitor_page_speed": true, "tags": [ "example" ], "http_version": "auto", "confirmation_threshold": 1, "json_path": "example", "json_path_expected": "example", "tls_port": 1, "alert_on_invalid_certificate": true, "recovery_period_runs": 1, "flap_hold": true, "flap_hold_override": true, "trace_propagation": true }'Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ”Makes a retry safe: the same key and body within 24 hours returns the first response with Idempotent-Replayed: true. The same key with another body is refused with 422 idempotency_key_reused, and one still running with 409 idempotency_key_in_use.
Request Body required
Section titled “Request Body required ”object
Assign the new monitor to a service in the same account.
Location ids. Left out or empty: GET /check-locations/default, one location, or
two on different providers on an uptime plan with room in its quota.
The HTTP method; required for http. TCP and ping monitors store TCP and PING.
Milliseconds. http up to 60000, tcp 1000 to 60000, ping 1000 to 10000.
http: the URL. tcp: tcp://host:port or host:port. ping: ping://host or
the host alone. IPv6 addresses go in brackets.
tcp only: sent once connected, with \r \n \t \0 \\ \xHH escapes. At most
1024 bytes after unescaping.
tcp only: the response must contain this (same escapes, case-sensitive), 1 to
256 bytes after unescaping. Left out, connecting is enough.
tcp only: complete a verified TLS handshake first. Defaults to false.
ping only: echo requests per check, 1 to 10. Defaults to 3.
ping only: fail when at least this percent of packets are lost, 1 to 100.
Defaults to 100, so only total loss fails.
http only. Sign check requests with Web Bot Auth so bot protection such as
Cloudflare recognizes SiteQwality Monitor, a verified bot. Defaults to off.
Notification groups to alert. Left out or null: the account’s default group. []: notify no one.
Pair a domain-expiry monitor. Defaults to true for http and false for tcp and
ping, which allow it only when the host is a domain name.
Number of consecutive failed checks (1-10) required before the monitor is considered down and notifications are sent. Defaults to 1 (alert on the first failed check).
Optional JSONPath assertion on the response body.
When set, the JSONPath result must stringify to this value.
Port the TLS check connects to, 1 to 65535. Omitted keeps the stored
port (443 for a new TLS check). Needs monitor_tls.
Alert when the certificate is one a browser would reject: expired, not yet
valid, self-signed, an untrusted chain or a hostname mismatch. Defaults to
true. Ignored without monitor_tls.
Healthy runs in a row (1-10) before a recovery is notified. Defaults to 2.
Deprecated: sets flap_hold_override when that is absent.
Hold alerts while the monitor flaps. Absent or null follows the account’s
notification setting.
Responses
Section titled “ Responses ”The monitor. warnings lists alert sources a channel in its groups cannot reach
object
Unique identifier for the HTTP job.
Unique identifier for the account associated with the HTTP job.
The current state of the HTTP job (e.g., active, paused).
Why a paused monitor is paused: user or dormancy (older rows may say billing).
The current status of the HTTP job (e.g., success, failure).
The regions from which the HTTP job will be checked.
The minimum number of healthy regions required for the HTTP job to be considered healthy.
A name set by the user to identify the HTTP job.
Indicates whether the HTTP job should follow redirects.
Reserved and currently unused.
The HTTP method used for the request (e.g., GET, POST).
A keyword to search for in the response body.
Indicates whether the keyword search is inverted (i.e., the job fails if the keyword is found).
Indicates whether the keyword search is case-sensitive, default is false.
Indicates whether to interpret the keyword search as a regex.
The timeout for the HTTP request in milliseconds.
The URI to which the HTTP request is sent.
http, tcp or ping; fixed once created.
TCP: sent once connected, with \r \n \t \0 \\ \xHH escapes.
TCP: the response must contain this, with the same escapes.
TCP: complete a verified TLS handshake before send and expect.
Ping: echo requests per check.
Ping: fail at or above this percent of packets lost.
Whether a failed run is checked once more before it counts: off,
same_location or another_cloud.
Whether check requests are signed with Web Bot Auth as SiteQwality Monitor.
The body of the HTTP request to be sent.
The username used for authentication.
True when a basic-auth password or a bearer token is stored for this
monitor. This is what a read gets in place of the secret itself; see
auth_type for which kind of credential it is.
A list of HTTP status codes that indicate a successful response.
A list of HTTP status codes that indicate a failed response.
A map of custom HTTP headers to be included in the request.
Names are returned. Values are readable only for the seven headers in
secrets::RETURNABLE_REQUEST_HEADERS, matched case-insensitively.
Other values become secrets::REDACTED; sending that placeholder back
preserves the stored value (secrets::restore_redacted_header_values).
The last time the HTTP job was run.
The last time the status of the HTTP job changed, (e.g., from success to failure).
The interval in seconds at which the HTTP job runs.
Indicates whether the HTTP job runs every 30 seconds.
A list of notification groups associated with the HTTP job. This is the same as
group_notification_ids, but with the full notification group object.
object
The group monitors get when they are created without group_notification_ids.
object
object
object
object
object
object
object
object
object
Severity of trigger events sent through this notification. Defaults
to critical when the caller omits it.
object
object
object
object
object
How this channel’s recent deliveries went: whether the last alert reached anyone, and why not when it did not (a revoked Slack token, a bouncing inbox). Present on the read endpoints; absent on create and update responses.
object
healthy: the most recent delivery reached the provider.
degraded: it was refused, bounced, complained about, could not be
sent, or skipped for a reason the channel must fix (such as
sms_quota), so the next alert will likely not arrive either.
unknown: nothing sent in the lookback window.
A skip by design, such as heartbeat_channel_unsupported, is listed in
recent but never judged.
Newest first, at most [CHANNEL_HEALTH_RECENT].
One delivery, as a channel’s health shows it.
object
Sent | delivered | delayed | soft_bounced | failed | rejected | bounced | complained | skipped
The provider’s reason for a non-success status, URLs reduced to hosts.
For skipped, a slug such as sms_quota or tls_channel_unsupported.
An email channel whose address hard-bounced or complained after its last delivery:
SES now suppresses it, so the channel is degraded until the address is fixed.
object
bounce or complaint.
E.g. Permanent/General, Permanent/OnAccountSuppressionList.
The ID of the TLS job associated with the HTTP job.
Indicates whether the HTTP job monitors TLS.
The ID of the DNS job associated with the HTTP job.
Indicates whether the HTTP job monitors DNS.
The ID of the page speed job associated with the HTTP job.
Indicates whether the HTTP job monitors page speed.
When the HTTP job was created.
A list of tags associated with the HTTP job.
The ID of the service this HTTP job belongs to.
Preferred HTTP version for the check client (auto / http1_1 / http2 / http2_with_fallback).
Number of consecutive failed checks required before the monitor is considered down and notifications are sent. 1 = alert on the first failed check.
Uptime percentage over the last 24h (successful checks / total) checks). Only populated on the monitor list endpoint; omitted when the monitor has no checks in the window.
Port the paired TLS check connects to. Only on GET /http/job/{id}
when TLS is monitored.
Whether an invalid certificate alerts. Only on GET /http/job/{id}
when TLS is monitored.
The website’s icon. Only on GET /http/job/{id}, once one is found.
object
Public HTTPS URL of the PNG. The same image always has the same URL.
How the icon reads on a transparent background: dark or light is a mark of that tone,
which needs a contrasting backdrop on a surface of the same tone. neutral reads on either.
Healthy runs in a row before a recovery is notified. 1 = notify on the first.
Whether alerts are held while the monitor flaps: the override, or else the account’s notification setting.
This monitor’s own flap hold; null follows the account’s notification setting.
Example
{ "state": "active", "current_status": "success", "check_type": "http", "recheck_on_failure": "off", "content_type": "json", "auth_type": "basic", "group_notifications": [ { "notifications": [ { "type": "email", "details": { "pagerduty_severity": "critical" } } ] } ], "http_version": "auto", "not_checked_reason": "quota", "icon": { "tone": "dark" }}Headers
Section titled “Headers ”true when this is the stored first response
Invalid request body, or a feature the plan lacks
An RFC 9457 problem, the body of every /v1 error.
object
https://docs.siteqwality.com/errors/ and the failure’s code, such as not_found.
urn:uuid: and the request id.
The invalid fields, when the request body was refused.
One validation failure; pointer is an RFC 6901 pointer into the request body.
object
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "errors": [ { "pointer": "example", "detail": "example" } ]}Missing or invalid credentials
An RFC 9457 problem, the body of every /v1 error.
object
https://docs.siteqwality.com/errors/ and the failure’s code, such as not_found.
urn:uuid: and the request id.
The invalid fields, when the request body was refused.
One validation failure; pointer is an RFC 6901 pointer into the request body.
object
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "errors": [ { "pointer": "example", "detail": "example" } ]}The plan’s monitor limit is reached
An RFC 9457 problem, the body of every /v1 error.
object
https://docs.siteqwality.com/errors/ and the failure’s code, such as not_found.
urn:uuid: and the request id.
The invalid fields, when the request body was refused.
One validation failure; pointer is an RFC 6901 pointer into the request body.
object
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "errors": [ { "pointer": "example", "detail": "example" } ]}The feature needs a paid plan
An RFC 9457 problem, the body of every /v1 error.
object
https://docs.siteqwality.com/errors/ and the failure’s code, such as not_found.
urn:uuid: and the request id.
The invalid fields, when the request body was refused.
One validation failure; pointer is an RFC 6901 pointer into the request body.
object
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "errors": [ { "pointer": "example", "detail": "example" } ]}No such service in this account
An RFC 9457 problem, the body of every /v1 error.
object
https://docs.siteqwality.com/errors/ and the failure’s code, such as not_found.
urn:uuid: and the request id.
The invalid fields, when the request body was refused.
One validation failure; pointer is an RFC 6901 pointer into the request body.
object
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "errors": [ { "pointer": "example", "detail": "example" } ]}Too many requests; wait for the time in Retry-After
An RFC 9457 problem, the body of every /v1 error.
object
https://docs.siteqwality.com/errors/ and the failure’s code, such as not_found.
urn:uuid: and the request id.
The invalid fields, when the request body was refused.
One validation failure; pointer is an RFC 6901 pointer into the request body.
object
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "errors": [ { "pointer": "example", "detail": "example" } ]}