Replace a monitor

Replaces a monitor configuration.

PUT https://app.upfour.io/v1/monitors/{monitorID}

A real request. Sending it changes data in your up4 account.

Authorization

AuthorizationA pls_ key. It stays in this browser tab. Needs monitor.write.

Path

monitorIDpath · requiredPart of the request path.

Body

staterequired UP, DOWN or PAUSED. Required on PUT; PATCH keeps the current state when omitted.

url

monitor_type

name interval_seconds

regions

What counts as up5

alert_type

keyword

keyword_case_insensitive

expected_status_code

ssl_verification

Request12

http_method

request_headers_action

request_body request_timeout_s

follow_redirects

keep_cookies

auth_username auth_password Basic-auth password. Write-only: responses carry has_auth_password instead.

auth_password_action

proxy_host proxy_port

ip_version

Alerting10

notification_mode

escalation_policy_id alert_plan_name

default_alert_plan

confirmation_period recovery_period

notify_recovery

degraded_alert_enabled

degraded_threshold_ms

capture_on_incident_open

Port and DNS checks6

tcp_host tcp_port dns_query dns_type dns_server dns_expected

Expiry warnings2

ssl_expiry_alert_days domain_expiry_alert_days

Maintenance window4

maintenance_from maintenance_to

maintenance_weekdays

maintenance_timezone

Organizing7

client_id client_name monitor_group_id monitor_group_name public_name pronounceable_name creation_key

4 more fields are only available in JSON.

Sent directly from your browser to https://app.upfour.io/v1. Mutating calls get an automatic Idempotency-Key when the field is empty.

Request

Responsenot sent yet

Fill in a key and press Send request (⌘↵).
The answer appears here.

scope monitor.write stable returns 200

Parameters

Field	Type	Description
`monitorID` required	uuid	path parameter

Body

The 6 fields most calls use come first; the rest are grouped below.

application/json required 56 fields

urlstring

monitor_typestring

httptcppingdns

namestring

interval_secondsinteger

regionsstring[]

euusasiaaudefault

notification_channel_idsuuid[]

What counts as up5 fields

alert_typestring

""statuskeywordkeyword_absenceexpected_status_code

keywordstring

keyword_case_insensitiveboolean · nullable

expected_status_codeinteger · nullable

ssl_verificationboolean · nullable

Request15 fields

http_methodstring

request_headersRequestHeader[]

Custom request headers, at most 20 and 8 KB in total. On update they are kept unless request_headers_action is replace or clear.

Nested fields 2 fields

Field	Type	Description
`name` optional	string
`value` optional	string

request_headers_actionstring

keepreplaceclear

request_bodystring

request_timeout_sinteger

follow_redirectsboolean · nullable

keep_cookiesboolean

auth_usernamestring

auth_passwordstring

Basic-auth password. Write-only: responses carry has_auth_password instead.

auth_password_actionstring

""keepreplaceclear

proxy_hoststring

proxy_portinteger · nullable

ip_versionstring

""46

Alerting11 fields

notification_modestring

quietimmediate

alert_channel_namesstring[]

escalation_policy_iduuid · nullable

alert_plan_namestring

default_alert_planboolean

confirmation_periodinteger

recovery_periodinteger

notify_recoveryboolean · nullable

degraded_alert_enabledboolean

degraded_threshold_msinteger · nullable

capture_on_incident_openboolean · nullable

Port and DNS checks6 fields

tcp_hoststring

tcp_portinteger · nullable

dns_querystring

dns_typestring

""AAAAAMXCNAMETXTNS

dns_serverstring

dns_expectedstring

Expiry warnings2 fields

ssl_expiry_alert_daysinteger · nullable

domain_expiry_alert_daysinteger · nullable

Maintenance window4 fields

maintenance_fromstring · nullable

maintenance_tostring · nullable

maintenance_weekdaysstring[]

montuewedthufrisatsun

maintenance_timezonestring

Organizing9 fields

client_iduuid · nullable

client_namestring

monitor_group_iduuid · nullable

monitor_group_namestring

public_namestring · nullable

pronounceable_namestring

metadatamap of stringmax 100 keyseach value max length 4096

On update, omitted or null leaves the stored metadata unchanged, {} removes all keys and any other object replaces them.

statestringrequired

UP, DOWN or PAUSED. Required on PUT; PATCH keeps the current state when omitted.

UPDOWNPAUSED

creation_keyuuid · nullable

Returns

A successful request returns 200 with application/json.

Response fields 1 top-level fields

Field Type Description

data Monitor

Monitor · 70 fields

Field Type Description

alert_type string one ofstatuskeywordkeyword_absenceexpected_status_code

auth_username string

capture_on_incident_open boolean

confirmation_period integer

created_at string (date-time)

degraded_alert_enabled boolean

degraded_threshold_ms integer · nullable

domain_expiry_alert_days integer · nullable

escalation_policy_id uuid · nullable

expected_status_code integer · nullable

feature_pause_reasons string[] · nullable

follow_redirects boolean

has_auth_password boolean

has_request_headers boolean

http_method string

id uuid

interval_seconds integer

ip_version string one of""46

is_degraded boolean

is_pending boolean

keep_cookies boolean

keyword string

keyword_case_insensitive boolean

maintenance_from string · nullable

maintenance_timezone string

maintenance_to string · nullable

maintenance_weekdays string[] · nullable one ofmontuewedthufrisatsun

monitor_type string one ofhttptcppingdns

name string

next_check_at string (date-time) · nullable

notification_mode string one ofquietimmediate

notify_recovery boolean

pronounceable_name string

proxy_host string

proxy_port integer · nullable

public_name string

recovery_period integer

regions string[] · nullable one ofeuusasiaaudefault

request_body string

request_headers any[] · nullable Always empty: header values are never returned. has_request_headers says whether the monitor sends any.

request_timeout_s integer

ssl_expiry_alert_days integer · nullable

ssl_verification boolean

state string one ofUPDOWNPAUSED

url string

user_id uuid

badge_token string

client_id uuid

dns_expected string

dns_query string

dns_server string

dns_type string one ofAAAAAMXCNAMETXTNS

freshness_timeout_seconds integer

last_checked_at string (date-time)

last_result_at string (date-time)

last_state_change_at string (date-time)

latency_p50_ms integer

latency_p95_ms integer

latency_samples_24h integer

latest_result_successful boolean

monitor_group_id uuid

paused_until string (date-time)

recent_incidents MonitorRecentIncident[]

Each item · 5 fields

Field	Type	Description
`id`	uuid
`resolved_at`	string (date-time) · nullable
`started_at`	string (date-time)
`status`	string
`resolved_by_type`	string

tcp_host string

tcp_port integer

Errors

Only the errors this operation can return. Every error uses the same envelope.

Status	Code	Meaning
400	`bad_request`	The request is malformed or fails validation.
403	`check_capacity_exceeded`	The change would push the subscription's projected monthly check load over its included budget. When: Creating a monitor, directly or through a client template, or changing one, when the projected cost including the change exceeds the budget; running monitors are not affected, and details carries projected_cents, included_cents and change_cents. Fix: Use a longer interval, fewer regions or fewer monitors, or raise the included budget. `check_capacity_exceeded` (subscriptions only): the change would raise the projected 30-day list usage of all active monitors above the included check budget. `error.details` carries `projected_cents`, `included_cents` and `change_cents`; a longer interval, fewer regions or fewer monitors fit. Running monitors and changes that lower the load are never refused.
403	`feature_disabled`	The monitor uses a feature that is currently switched off. When: Saving a monitor whose configuration needs a feature the platform has disabled; the saved configuration stays as it was. Fix: Remove that feature from the monitor, or try again once the feature is back.
404	`not_found`	The requested resource does not exist or is outside the caller's scope.
402	`payment_required`	The account does not have the credit or plan required for this action.
403	`permission_denied`	The credentials do not permit this action.

Every call can also return unauthorized (401), rate_limit_exceeded (429) or internal_error (500 / 502). See Responses and errors.

curl -s -X PUT "https://app.upfour.io/v1/monitors/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "interval_seconds": 60, "monitor_type": "http", "name": "Marketing website", "state": "UP", "url": "https://example.com" }'

const res = await fetch("https://app.upfour.io/v1/monitors/00000000-0000-4000-8000-000000000001", { method: "PUT", headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ interval_seconds: 60, monitor_type: "http", name: "Marketing website", state: "UP", url: "https://example.com", }), }); console.log(res.status, await res.json());

import os import requests res = requests.put( "https://app.upfour.io/v1/monitors/00000000-0000-4000-8000-000000000001", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "interval_seconds": 60, "monitor_type": "http", "name": "Marketing website", "state": "UP", "url": "https://example.com", }, ) print(res.status_code, res.json())

package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "interval_seconds": 60, "monitor_type": "http", "name": "Marketing website", "state": "UP", "url": "https://example.com" }`) req, _ := http.NewRequest("PUT", "https://app.upfour.io/v1/monitors/00000000-0000-4000-8000-000000000001", payload) req.Header.Set("Authorization", "Bearer "+os.Getenv("UP4_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(out)) }

<?php $payload = <<<'JSON' { "interval_seconds": 60, "monitor_type": "http", "name": "Marketing website", "state": "UP", "url": "https://example.com" } JSON; $ch = curl_init("https://app.upfour.io/v1/monitors/00000000-0000-4000-8000-000000000001"); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("UP4_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $response, "\n"; curl_close($ch);

{ "data": { "alert_type": "status", "auth_username": "", "capture_on_incident_open": false, "confirmation_period": 0, "created_at": "2026-10-27T09:00:00Z", "degraded_alert_enabled": false, "degraded_threshold_ms": null, "dns_type": "A", "domain_expiry_alert_days": null, "escalation_policy_id": null, "expected_status_code": null, "feature_pause_reasons": [], "follow_redirects": true, "freshness_timeout_seconds": 120, "has_auth_password": false, "has_request_headers": false, "http_method": "HEAD", "id": "00000000-0000-4000-8000-000000000001", "interval_seconds": 60, "ip_version": "", "is_degraded": false, "is_pending": false, "keep_cookies": false, "keyword": "", "keyword_case_insensitive": true, "last_result_at": "2026-10-27T08:50:00Z", "latest_result_successful": true, "maintenance_from": null, "maintenance_timezone": "UTC", "maintenance_to": null, "maintenance_weekdays": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "monitor_type": "http", "name": "Marketing website", "next_check_at": "2026-10-27T09:00:00Z", "notification_mode": "immediate", "notify_recovery": true, "pronounceable_name": "", "proxy_host": "", "proxy_port": null, "public_name": "", "recovery_period": 0, "regions": [ "eu" ], "request_body": "", "request_headers": [], "request_timeout_s": 30, "ssl_expiry_alert_days": null, "ssl_verification": true, "state": "UP", "url": "https://example.com", "user_id": "00000000-0000-4000-8000-000000000002" } }

{ "error": { "code": "check_capacity_exceeded", "message": "The change would push the subscription's projected monthly check load over its included budget.", "request_id": "req_…" } }