Create Monitor

Create a new monitor to start tracking uptime

Overview

Create a monitor that checks an endpoint, server or scheduled job on a fixed interval. Six monitor types are supported: HTTP, KEYWORD, ICMP (ping), TCP (port), DNS and HEARTBEAT. Checking starts as soon as the monitor is created.

POST https://api.uptimeio.com/api/monitors

Authentication

Header	Required	Description
X-API-Key	Yes (or a Bearer token)	Your API key. It must have read and write access; read-only keys receive READ_ONLY_API_KEY (403). See Authentication.
Content-Type	Yes	application/json
X-Project-ID	No	Project that will own the monitor. Defaults to your organization’s default project.

Creating a monitor also requires a verified email address on the account that owns the key (otherwise EMAIL_NOT_VERIFIED, 403) and a role that can create monitors (otherwise INSUFFICIENT_PERMISSIONS, 403).

Request body

Common fields

Field	Type	Required	Description
name	string	Yes	Display name, 1-80 characters.
type	enum	Yes	HTTP, KEYWORD, ICMP, TCP, DNS or HEARTBEAT. Cannot be changed later.
target	string	Yes (except HEARTBEAT)	What to check. A full URL for HTTP and KEYWORD; a hostname or IP address for ICMP, TCP and DNS (TCP also accepts host:port). Not used for HEARTBEAT; a ping URL is generated for you. Maximum 2048 characters.
interval_seconds	integer	Yes	Seconds between checks, 30-86400, and never below your plan minimum (Free 300, Pro and Scale 60).
monitoring_regions	array of strings	Yes	[] lets UptimeIO choose the locations automatically. A non-empty array pins regular checks to those locations (see Probe locations below). Maximum 10 entries.
timeout_ms	integer	No	Per-check timeout, 1000-60000. Must be shorter than the check interval. Default 10000.
tags	array of strings	No	Free-form labels. Default [].
group_id	UUID	No	Monitor group to place the monitor in.
notification_target_ids	array of UUIDs	No	Notification destinations that receive this monitor’s alerts.
ssl_monitoring	object	No	Certificate expiry warnings. See SSL certificate monitoring.
domain_monitoring	object	No	Domain registration expiry warnings. See Domain expiry monitoring.
verify_ssl	boolean	No	Validate the TLS certificate on HTTP and KEYWORD checks. Default true.

Probe locations

UptimeIO checks from multiple locations (see Probe locations). The monitoring_regions values you can send are listed by the public GET /api/regions endpoint.

• Use [] to let UptimeIO pick among the available locations. This is the only option on the Free plan.
• Pro and Scale can pin regular checks to one or more locations. At least one location is enough.
• A region group code (europe, north-america, asia, oceania) selects every location in that group. GET /api/regions needs no authentication.
• A location with no active probe is rejected with INVALID_REGIONS.
• An incident is only opened after failures are confirmed from more than one location. The confirming checks use other locations automatically, so selecting a single location does not weaken that protection.

HTTP monitor

Check a URL and expect a status code.

{
  "name": "Production API",
  "type": "HTTP",
  "target": "https://api.example.com/health",
  "interval_seconds": 60,
  "timeout_ms": 10000,
  "monitoring_regions": ["netherlands", "us-west"],
  "tags": ["production"],
  "http_config": {
    "method": "GET",
    "headers": { "Accept": "application/json" },
    "follow_redirects": true,
    "max_redirects": 5,
    "expected_status_codes": [200, 204],
    "slow_response_threshold_ms": 2000
  }
}

http_config fields:

Field	Type	Required	Description
method	enum	Yes	GET, POST, PUT, DELETE, HEAD, OPTIONS or PATCH.
headers	object	No	Request headers (string values).
body	string	No	Request body.
content_type	string	No	Content type for the body.
follow_redirects	boolean	No	Default true.
max_redirects	integer	No	0-10. Default 5.
expected_status_codes	array of integers	No	Each 100-599. Default [200].
auth	object	No	{ "type": "basic" | "digest", "username": "...", "password": "..." }.
slow_response_threshold_ms	integer	No	Raise a slow-response alert above this response time. The slow-response incident resolves once the response time stays below 80% of the threshold for 3 consecutive checks.

auth is accepted but is not applied to checks. To send credentials, set an Authorization header in headers instead.

Keyword monitor

Fetch a URL and check the response for words that must, or must not, be present.

{
  "name": "Storefront is in stock",
  "type": "KEYWORD",
  "target": "https://shop.example.com/products",
  "interval_seconds": 300,
  "monitoring_regions": [],
  "keyword_config": {
    "method": "GET",
    "keywords": [
      { "text": "Add to cart", "should_contain": true },
      { "text": "Out of stock", "should_contain": false }
    ],
    "match_mode": "all",
    "case_sensitive": false
  }
}

keyword_config fields:

Field	Type	Required	Description
method	enum	Yes	GET, POST, PUT, DELETE, OPTIONS or PATCH.
keywords	array	One of keywords or keyword	1-20 entries of { "text": string (1-500 chars), "should_contain": boolean }. should_contain: true means the text must appear; false means the check fails if it appears.
match_mode	enum	No	all (default) or any. How the should_contain: true keywords combine: every one must appear, or at least one. Forbidden keywords (should_contain: false) always fail the check when found, regardless of mode.
case_sensitive	boolean	No	Default false.
keyword	string	No	Legacy single keyword. Ignored when keywords is present.
should_contain	boolean	No	Legacy polarity for keyword. Default true.
slow_response_threshold_ms	integer	No	Slow-response alert threshold.

Set request headers, body, redirect handling and expected status codes for a keyword monitor through http_config (same fields as above).

ICMP (ping) monitor

{
  "name": "Web server ping",
  "type": "ICMP",
  "target": "web01.example.net",
  "interval_seconds": 300,
  "monitoring_regions": [],
  "icmp_config": { "packet_count": 4, "packet_size": 64, "timeout_ms": 10000 }
}

Field	Type	Default	Range
packet_count	integer	4	1-10
packet_size	integer	64	1-1472 bytes
timeout_ms	integer	10000	1-60000
ttl	integer	none	1-255

Each check sends packet_count echo requests of packet_size bytes, about one second apart, and succeeds if at least one reply is received. Values above the ranges are rejected with a validation error. A check ends at timeout_ms, so keep timeout_ms at least packet_count seconds; packets not yet sent by then are not counted.

TCP (port) monitor

{
  "name": "Mail server SMTP",
  "type": "TCP",
  "target": "mail.example.net",
  "interval_seconds": 300,
  "monitoring_regions": [],
  "tcp_config": {
    "port": 25,
    "protocol": "smtp",
    "protocol_validation": { "smtp": { "expect_banner": true } }
  }
}

Field	Type	Required	Description
port	integer	Yes	1-65535.
protocol	enum	No	smtp, pop3, imap, ftp, ssh or generic (default). A label stored with the monitor; generic is a plain connection test. http and https are rejected with a VALIDATION_FAILED error (“HTTP and HTTPS are not supported for port monitors. Use an HTTP monitor instead.”); create an HTTP monitor to check a web page.
connection_timeout_ms	integer	No	1-60000. Default 10000.
protocol_validation	object	No	Optional extra checks: smtp: { expect_banner, test_command? }; pop3, ftp, imap: { expect_banner }. expect_banner: true expects the server greeting (220 for SMTP and FTP, +OK for POP3, * OK for IMAP).

The ssh protocol is a connection test only; its banner is not checked. A check with no data to send and no expected response succeeds as soon as the connection is accepted.

DNS monitor

{
  "name": "WWW A record",
  "type": "DNS",
  "target": "www.example.net",
  "interval_seconds": 300,
  "monitoring_regions": [],
  "dns_config": {
    "record_entries": [
      {
        "id": "a-record",
        "record_type": "A",
        "expected_values": ["203.0.113.10"],
        "validation_mode": "exact"
      }
    ],
    "dns_server": "1.1.1.1",
    "resolution_timeout_ms": 5000
  }
}

Field	Type	Required	Description
record_entries	array	Yes	1-10 entries (below).
record_entries[].id	string	Yes	Your identifier for the entry.
record_entries[].record_type	enum	Yes	A, AAAA, CNAME, MX, TXT or NS.
record_entries[].expected_values	array of strings	Yes	At least one value.
record_entries[].validation_mode	enum	Yes	exact, contains or regex.
dns_server	string	No	Resolver IP address to query (a hostname is rejected). Default: the probe’s resolvers.
resolution_timeout_ms	integer	No	1-60000. Default 5000.

Validation modes: exact passes when every expected value appears in the resolved values; contains passes when at least one does; regex passes when at least one resolved value matches one of the expected values treated as a regular expression. The monitor succeeds only when all entries pass, and an entry fails when no records of its type exist. For MX records only the mail server hostname is compared, not the priority.

Heartbeat monitor

UptimeIO waits for your job to ping a generated URL. target is not needed.

{
  "name": "Nightly backup",
  "type": "HEARTBEAT",
  "interval_seconds": 86400,
  "monitoring_regions": [],
  "heartbeat_config": {
    "expected_interval_seconds": 86400,
    "grace_period_seconds": 600
  }
}

Field	Type	Required	Description
expected_interval_seconds	integer	Yes	How often the job should ping. At least 60. The monitor’s interval_seconds is set to this value.
grace_period_seconds	integer	Yes	Extra time allowed before a missed ping counts. At most 3600.
notification_delay_minutes	integer	No	Default 5.
max_consecutive_misses	integer	No	Default 3.

The response contains heartbeat_token. Your job pings the URL /heartbeat/{heartbeat_token}; the full ping URL, including host, is shown on the monitor in the dashboard. See Heartbeat monitors.

Heartbeat ping endpoint

Pings go to https://heartbeat.uptimeio.com/heartbeat/{token} or the same path on api.uptimeio.com. Both hosts behave identically. The URL needs no authentication; the token is the credential. Send GET or POST. A POST may carry an optional JSON metadata object: up to 10 keys (letters, digits, _, -; 1-100 characters), values that are strings (up to 500 characters), numbers or booleans, about 2 KB in total, with the request body limited to 20 KB. A body that is not valid JSON is ignored and the ping is still recorded.

A successful ping returns 200 with { "success": true, "data": { "message": "Heartbeat received", "timestamp": 1790000000000 } }.

Status	Code	Meaning
400	INVALID_TOKEN	The token is malformed. Tokens start with hb_.
404	INVALID_TOKEN	The token is well-formed but no monitor uses it.
400	INVALID_METADATA	The metadata value failed validation.
429	RATE_LIMIT_EXCEEDED	Limit: 3 requests per 30 seconds per URL on all plans, plus 1 request per 120 seconds on Free. Wait for the Retry-After header value.

SSL certificate monitoring

Applies to HTTP and KEYWORD monitors on https:// targets.

{ "ssl_monitoring": { "enabled": true, "check_expiry": true, "expiry_warning_days": [30, 15, 7, 1] } }

Field	Type	Default	Description
enabled	boolean	required	Turn SSL monitoring on or off.
check_expiry	boolean	true	Send warnings before the certificate expires. Warnings go to your notification channels and do not open an incident.
check_validity	boolean	true	An expired or invalid certificate opens an incident, which resolves automatically once a valid certificate is served.
expiry_warning_days	array	[7, 1]	Any of 30, 15, 7, 1. At least one is required when enabled and check_expiry are true.
ignore_self_signed	boolean	none	Do not alert on self-signed certificates.

Domain expiry monitoring

Warns you before the registration of the monitored domain expires.

{ "domain_monitoring": { "enabled": true, "expiry_warning_days": [30, 7] } }

Field	Type	Required	Description
enabled	boolean	Yes	Turn domain expiry warnings on or off.
expiry_warning_days	array	No	Any of 30, 15, 7, 1 (at most 4). Default [30, 15, 7, 1]. At least one is required when enabled is true. Stored de-duplicated and sorted, largest first.

How it works:

• Registration data is looked up via RDAP and refreshed hourly; it is not re-read on every check.
• Only HTTP, KEYWORD and DNS monitors whose target is a publicly registered domain qualify. IP addresses, localhost and internal names (for example db.internal) are rejected with VALIDATION_ERROR (400), with details.field set to domain_monitoring.
• The registered domain is what is checked: https://api.eu.example.co.uk/health is checked as example.co.uk, and a hosted subdomain such as myapp.herokuapp.com as herokuapp.com.
• Some country-code registries do not publish an expiry date (many .de domains, for example). For those the expiry is reported as not published and no warnings are sent.
• GET /api/monitors/{id}/domain-info returns domain, status, expires_at, days_until_expiry and registrar for the monitor’s domain.

Response

201 Created

{
  "success": true,
  "data": {
    "monitor": {
      "id": "b7a2c1de-3f54-4c21-9d0a-6e1f2a3b4c5d",
      "organization_id": "0c9e8d7f-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "created_by": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c",
      "name": "Production API",
      "target": "https://api.example.com/health",
      "type": "HTTP",
      "interval_seconds": 60,
      "status": "active",
      "configState": "active",
      "runtimeStatus": "unknown",
      "created_at": 1767000000,
      "updated_at": 1767000000,
      "method": "GET",
      "headers": { "Accept": "application/json" },
      "timeout_ms": 10000,
      "expected_status": [200, 204],
      "follow_redirects": true,
      "verify_ssl": true,
      "slow_response_threshold_ms": 2000
    }
  }
}

The monitor object carries the fields relevant to its type (for example keyword_config, tcp_config, dns_config, icmp_config, ssl_monitoring, domain_monitoring, heartbeat_token). created_at and updated_at are Unix timestamps in seconds. monitoring_regions and tags are accepted when you write a monitor but are not included in monitor responses. See Get Monitor for the full field list.

Plan limits

	Free	Pro	Scale
Monitors	50	100	500
Minimum interval	300 s (5 min)	60 s (1 min)	60 s (1 min)
Pin probe locations	No (use [])	Yes	Yes
Heartbeat, DNS, SSL, domain expiry, slow-response alerts	Yes	Yes	Yes

Errors

Errors use the standard envelope (see Errors).

Status	Code	Cause
400	VALIDATION_ERROR	The body failed validation, the target is not allowed for the monitor type, or domain_monitoring was enabled on an ineligible monitor. message lists the failing fields, for example Validation failed: interval_seconds: Interval must be at least 30 seconds.
400	VALIDATION_FAILED	heartbeat_config is missing or out of range on a HEARTBEAT monitor.
400	INVALID_REGIONS	A region code is unknown or has no active probe.
400	MONITOR_CREATION_FAILED	The monitor could not be created.
401	AUTHENTICATION_REQUIRED / MISSING_AUTH / INVALID_API_KEY	Missing or invalid credentials.
403	READ_ONLY_API_KEY	The key has read-only access.
403	EMAIL_NOT_VERIFIED	Verify the account email first.
403	INSUFFICIENT_PERMISSIONS	Your role cannot create monitors.
403	MONITOR_LIMIT_REACHED	You have reached your plan’s monitor limit.
403	INTERVAL_TOO_SHORT	interval_seconds is below your plan minimum.
403	LOCATION_MONITORING_NOT_AVAILABLE	A non-empty monitoring_regions was sent on the Free plan.

Targets are rejected when they point at private or reserved IP ranges, localhost and *.local, *.internal, *.lan names, well-known third-party domains, or the apex of example.com, example.org, example.net and test.com for HTTP and KEYWORD monitors. Subdomains such as api.example.com are allowed.

Example

cURL

curl -X POST https://api.uptimeio.com/api/monitors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "type": "HTTP",
    "target": "https://api.example.com/health",
    "interval_seconds": 60,
    "monitoring_regions": [],
    "http_config": { "method": "GET", "expected_status_codes": [200] },
    "ssl_monitoring": { "enabled": true, "expiry_warning_days": [30, 15, 7, 1] },
    "domain_monitoring": { "enabled": true }
  }'