POST/v1/monitors

Create a monitor

Creates a new monitor: HTTP, port, ping (ICMP), DNS, or a Playwright browser check.

Request

Bodyapplication/json

namestringrequired

Pronounceable name of the monitor

Example:"My Website"

external_idstringoptional

Your own identifier for the monitor, unique within the project: 1 to 128 letters, digits, ., _, : or -, starting with a letter or a digit. Creating a second monitor with the same external_id returns 409 with the uuid of the monitor that has it. To create or update by this identifier, use Create or update a monitor.

Example:"client-42"

urlstringrequired

The URL of your website, or hostname (for DNS/ICMP/port monitors) you want to check. Optional for a browser check, whose target is in its script: when set, it is shown with the monitor.

Example:"https://acme.com"

protocolenum<string>optional

Type of monitor to create. browser creates a browser check that runs the Playwright test in script. To create many of them from one script, see Create browser checks with the API.

Available options:

httpporticmpdnsbrowser

Default: http

scriptstringrequired for browser

The Playwright test of a browser check, the same code you would paste in the dashboard editor (@playwright/test, TypeScript or JavaScript). Required when protocol is browser and refused for the other protocols. Up to 100,000 characters. New browser checks run on runtime 2026.05.

env_variablesarray<object>optional

Variables the script reads as process.env.NAME: credentials, or what changes between checks that share one script, like the URL to open. Objects with name and value. Names use letters, digits and _ and don't start with a digit; values are up to 4096 bytes. Values are stored encrypted and never returned by the API. Browser checks only, up to 50 variables.

Example:[{ "name": "BASE_URL", "value": "https://help.acme.com" }]

dns_record_typeenum<string>optional

DNS record type to check. Only used when protocol is dns

Available options:

AAAAACNAMEMXNSTXTSOASRVCAAPTR

Default: A

dns_nameserverstringoptional

Nameserver to query against (e.g. 8.8.8.8). Leave empty to use default resolvers. Only used when protocol is dns

Example:"8.8.8.8"

dns_expected_answerstringoptional

Expected DNS answer to validate against. Monitor fails if the resolved value does not contain this string. Only used when protocol is dns

Example:"192.0.2.1"

regionsarray<string>optional

Array of region names to monitor from. Browser checks run from frankfurt and sanfrancisco, and use both by default.

Available options:

sanfrancisconyclondonparisfrankfurtseoulmumbaibangaloresaopaulocaliforniavirginiasydneytorontoamsterdamsingaporetokyobahraincapetown

Default: all regions

check_frequencynumberoptional

Check frequency in seconds. A browser check takes 300, 600, 900, 1800, 3600, 21600, 43200 or 86400, and defaults to 300.

Available options:

1020306012018030060018003600216004320086400

Default: 30 (300 for a browser check)

http_methodenum<string>optional

HTTP method for the request

Available options:

GETPOSTPUTHEADDELETEPATCHOPTIONS

Default: GET

request_bodystringoptional

Request body for POST, PUT, PATCH requests

request_headersarray<object>optional

Array of objects with name and value properties for custom HTTP headers

follow_redirectsbooleanoptional

Whether to follow HTTP redirects

Default: true

ip_versionenum<number>optional

IP version used to reach the target: 4 or 6. An IPv6 monitor is checked over IPv6 only, never IPv4. Available for the http, port and icmp protocols. Checks run only from the selected regions that have an IPv6 probe, and the request is rejected if none of the selected regions has one. See IP version.

Available options:

Default: 4

portnumberoptional

Port number to check. Required if protocol is port

Example:443

expected_status_codestringoptional

Expected HTTP status code. Use "2xx" for 200-299, "1xx-3xx" for 100-399, or a specific code like "200".

Example:"2xx"

Default: 2xx (200-299)

required_keywordstringoptional

Triggers downtime if body response is missing this keyword

pausedbooleanoptional

Whether the monitor should be paused

Default: false

alerts_waitnumberoptional

Minutes to wait before sending alerts. Use -1 to disable alerts.

Available options:

-101235103060

Default: 0

ssl_alert_daysnumberoptional

Days before the TLS certificate expires to send the first expiry alert. -1 = never. When omitted on create, the default applies.

Available options:

-113715306090

ssl_remindersbooleanoptional

Also remind at each step below the threshold (30, 15, 7, 3 and 1 days). Default true.

ssl_notify_on_changebooleanoptional

Notify when the server starts serving a different certificate. Default false.

domain_alert_daysnumberoptional

Days before the domain registration expires to alert. -1 = never (default for monitors created through the API).

Available options:

-1714306090

group_idnumberoptional

Monitor group to put the monitor in, from the Monitor Groups API. The monitor goes last in the group unless sort_order is set.

Example:12

sort_ordernumberoptional

Position of the monitor in its group

escalation_policystringoptional

Policy UUID to link. Send null or "none" to unlink.

Example:"policy_123abc"

Response

Returns the newly created monitor object with status code 201, or 409 with message and uuid when the external_id is already used in the project.

RequestcURL

curl -X POST https://api.hyperping.io/v1/monitors \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website",
    "url": "https://acme.com",
    "regions": ["paris", "frankfurt", "amsterdam", "london"],
    "http_method": "GET",
    "check_frequency": 30,
    "request_headers": [
      { "name": "X-Request-Header", "value": "Header value" }
    ],
    "protocol": "http"
  }'

201 CreatedJSON

{
  "name": "Website",
  "url": "https://acme.com",
  "paused": false,
  "regions": [
    "paris",
    "frankfurt",
    "amsterdam",
    "london"
  ],
  "http_method": "GET",
  "check_frequency": 30,
  "request_headers": [
    {
      "name": "X-Request-Header",
      "value": "Header value"
    }
  ],
  "protocol": "http",
  "port": null,
  "follow_redirects": true,
  "ip_version": 4,
  "expected_status_code": "2xx",
  "request_body": "",
  "projectUuid": "0109c1f0-b521-44f4-9681-9046aa6f51d8",
  "uuid": "mon_3GhAQMYGEQuyUH",
  "status": "up",
  "ssl_expiration": 90,
  "ssl_alert_days": 30,
  "ssl_reminders": true,
  "ssl_notify_on_change": false,
  "domain_alert_days": 30,
  "domain_expiration": 214,
  "alerts_wait": 0
}

Request: browser checkcURL

curl -X POST https://api.hyperping.io/v1/monitors \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Help center - Acme",
    "protocol": "browser",
    "url": "https://help.acme.com",
    "check_frequency": 300,
    "group_id": 12,
    "script": "import { test, expect } from \"@playwright/test\";\n\ntest(\"help center loads\", async ({ page }) => {\n  await page.goto(process.env.BASE_URL);\n  await expect(page.getByRole(\"searchbox\")).toBeVisible();\n});\n",
    "env_variables": [
      { "name": "BASE_URL", "value": "https://help.acme.com" }
    ]
  }'

201 CreatedJSON

{
  "name": "Help center - Acme",
  "url": "https://help.acme.com",
  "uuid": "mon_7BLzvBqgJYdvpm",
  "protocol": "browser",
  "projectUuid": "0109c1f0-b521-44f4-9681-9046aa6f51d8",
  "paused": false,
  "regions": [
    "frankfurt",
    "sanfrancisco"
  ],
  "check_frequency": 300,
  "status": "up",
  "alerts_wait": 0,
  "group_id": 12,
  "sort_order": 4,
  "escalation_policy": null,
  "env_variables": [
    { "name": "BASE_URL" }
  ],
  "script": "import { test, expect } from \"@playwright/test\";\n\ntest(\"help center loads\", async ({ page }) => {\n  await page.goto(process.env.BASE_URL);\n  await expect(page.getByRole(\"searchbox\")).toBeVisible();\n});\n"
}

← Get a monitor Update a monitor →