Skip to content
Pong Docs

Create a monitor

POST
/api/v1/monitors

Creates a new monitor for the authenticated user.

For heartbeat monitors the target field is not required; the backend will generate a unique heartbeat_token that can be used to ping the heartbeat endpoint.

Default values when not specified:

  • interval_secs: 300
  • timeout_secs: 30
  • expected_status: 200
  • confirmation_count: 1
  • ssl_warn_days: 30

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Request body for creating a new monitor.

object
name
required

Human-readable name for the monitor.

string
Example
Production API
type
required

The kind of check this monitor performs.

string
Allowed values: http ssl heartbeat keyword port dns
Example
http
target

URL, hostname, or address to monitor. Not required for heartbeat monitors.

string
Example
https://api.example.com/healthz
interval_secs

Seconds between checks.

integer
default: 300
Example
300
timeout_secs

Seconds before a check is considered timed out.

integer
default: 5
Example
5
keyword

Keyword to search for (keyword monitors only).

string
Example
ok
keyword_type

Whether the keyword should or should not appear.

string
Allowed values: contains not_contains
Example
contains
keyword_match

Match mode for keyword checks. “exact” for plain string, “regex” for regular expression.

string
default: exact
Allowed values: exact regex
Example
exact
expected_status

Expected HTTP status code.

integer
default: 200
Example
200
latency_warn_ms

Latency warning threshold in milliseconds.

integer
Example
1000
confirmation_count

Consecutive failures required before marking as down.

integer
default: 1
Example
1
ssl_warn_days

Days before SSL expiry to warn.

integer
default: 30
Example
30
heartbeat_secret

Optional secret for heartbeat monitors. If set, pings must include the X-Secret header with this value.

string
Example
a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5
protocol

Network protocol for port monitors.

string
default: tcp
Allowed values: tcp udp
Example
tcp
http_auth_type

Type of HTTP authentication. Requires ENCRYPTION_KEY to be configured.

string
Allowed values: none basic header
Example
basic
http_auth_username

Username for Basic Auth (required when http_auth_type is “basic”).

string
Example
admin
http_auth_password

Password for Basic Auth (required when http_auth_type is “basic”).

string
Example
secret123
http_auth_header

Header name for custom header auth (required when http_auth_type is “header”).

string
Example
X-API-Key
http_auth_value

Header value for custom header auth (required when http_auth_type is “header”).

string
Example
my-api-key
dns_record_type

DNS record type (DNS monitors only). Defaults to A.

string
Allowed values: A AAAA MX TXT CNAME NS
Example
A
dns_expected_value

Optional case-insensitive substring expected in at least one DNS record.

string
Example
93.184.216.34
dns_resolver

Optional custom DNS resolver (e.g. “1.1.1.1”). Defaults to the system resolver.

string
Example
1.1.1.1
alert_contact_ids

IDs of alert contacts to attach.

Array<integer>
Example
[
  1,
  3
]
Examples

HTTP monitor

{
  "name": "Production API",
  "type": "http",
  "target": "https://api.example.com/healthz",
  "interval_secs": 60,
  "expected_status": 200,
  "alert_contact_ids": [
    1
  ]
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Monitor created successfully.

A monitor that periodically checks the health of a target.

object
id
required

Unique monitor identifier.

integer
Example
42
user_id
required

ID of the user who owns this monitor.

integer
Example
1
name
required

Human-readable name for the monitor.

string
Example
Production API
type
required

The kind of check this monitor performs.

string
Allowed values: http ssl heartbeat keyword port dns
Example
http
target
required

URL, hostname, or address to monitor.

string
Example
https://api.example.com/healthz
interval_secs
required

Seconds between checks.

integer
Example
300
timeout_secs
required

Seconds before a check is considered timed out.

integer
Example
5
protocol

Network protocol for port monitors.

string
default: tcp
Allowed values: tcp udp
Example
tcp
keyword

Keyword to search for in the response body (keyword monitors only).

string
nullable
Example
ok
keyword_type

Whether the keyword should or should not appear in the response.

string
nullable
Allowed values: contains not_contains
Example
contains
keyword_match

Match mode for keyword checks. “exact” for plain string, “regex” for regular expression.

string
default: exact nullable
Allowed values: exact regex
Example
exact
expected_status

Expected HTTP status code (HTTP monitors).

integer
nullable
Example
200
latency_warn_ms

Latency threshold in milliseconds that triggers a warning.

integer
nullable
Example
1000
confirmation_count
required

Number of consecutive failures required before marking the monitor as down.

integer
Example
1
consecutive_fails
required

Current count of consecutive check failures.

integer
0
heartbeat_token

Unique token for heartbeat monitors. Generated by the backend.

string
nullable
Example
hb_a1b2c3d4e5f6
heartbeat_last_ping

Timestamp of the last heartbeat ping received.

string format: date-time
nullable
Example
2026-03-29T10:15:00Z
heartbeat_secret

Optional secret for heartbeat monitors. If set, pings must include the X-Secret header with this value.

string
nullable
Example
a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5
ssl_warn_days

Number of days before SSL expiry to trigger a warning.

integer
nullable
Example
30
ssl_expiry_at

SSL certificate expiry timestamp.

string format: date-time
nullable
Example
2026-12-01T00:00:00Z
enabled
required

Whether the monitor is actively running checks.

boolean
Example
true
status
required

Current status of the monitored target.

string
Allowed values: up down unknown
Example
up
last_checked_at

Timestamp of the most recent check.

string format: date-time
nullable
Example
2026-03-29T12:00:00Z
created_at
required

When the monitor was created.

string format: date-time
Example
2026-01-15T08:30:00Z
updated_at
required

When the monitor was last updated.

string format: date-time
Example
2026-03-29T12:00:00Z
alert_contact_ids

IDs of alert contacts to notify when the monitor changes state.

Array<integer>
nullable
Example
[
  1,
  3
]
http_auth_type

Type of HTTP authentication configured on this monitor.

string
Allowed values: none basic header
Example
none
http_auth_configured

Whether HTTP authentication credentials are configured. Credentials are never returned in responses.

boolean
dns_record_type

DNS record type to resolve (DNS monitors only).

string
nullable
Allowed values: A AAAA MX TXT CNAME NS
Example
A
dns_expected_value

Optional case-insensitive substring that must appear in at least one returned DNS record.

string
nullable
Example
93.184.216.34
dns_resolver

Optional custom DNS resolver (e.g. “1.1.1.1” or “8.8.8.8:53”). Defaults to the system resolver.

string
nullable
Example
1.1.1.1

400

Section titled “400 ”

The request body is invalid or missing required fields.

Error response returned when a request fails.

object
error
required

A human-readable error message.

string
Example
monitor not found
Example
{
  "error": "invalid request body"
}

401

Section titled “401 ”

Authentication credentials are missing or invalid.

Error response returned when a request fails.

object
error
required

A human-readable error message.

string
Example
monitor not found
Example
{
  "error": "unauthorized"
}