/monitors/{id} (PATCH)

PATCH

/monitors/{id}

const url = 'https://culipulse.dev/v1/monitors/mon_123';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","target":"https://api.example.com/health","interval_seconds":60,"timeout_ms":1,"method":"example","expected_status":"2xx","body_match":"example","follow_redirects":true,"down_after_failures":1,"up_after_successes":1,"down_min_sources":1,"sla_target":1,"grace_seconds":1,"agent_sources":["example"],"check_spec":{"request":{"headers":{"additionalProperty":"example"},"secretHeaders":{"additionalProperty":"example"},"preserveSecretHeaders":true,"secretHeaderNames":["example"],"auth":{"type":"bearer","token":"example","username":"example","password":"example"},"body":"example","bodySecret":true,"preserveBody":true,"contentType":"example"},"assertions":[{"source":"text_body","op":"example","value":"example","path":"example","name":"example"}],"transport":{"payload":"example","payloadEncoding":"utf8","expect":"example","expectMode":"contains","payloadSecret":true,"preservePayload":true},"domain":{"warnDays":1},"ping":{"count":1,"lossDegradedPct":1,"rttDegradedMs":1},"heartbeat":{"token":"example","failEnabled":true,"maxDurationSeconds":1},"dns":{"records":[{"type":"example","mode":"example","expected":["example"]}],"crossCheck":true},"vendor":{"vendorId":"example","pageUrl":"example","probeUrl":"example","components":["example"]},"dependencies":["example"]},"warn_days":1,"components":["example"],"dependencies":["example"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://culipulse.dev/v1/monitors/mon_123 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "target": "https://api.example.com/health", "interval_seconds": 60, "timeout_ms": 1, "method": "example", "expected_status": "2xx", "body_match": "example", "follow_redirects": true, "down_after_failures": 1, "up_after_successes": 1, "down_min_sources": 1, "sla_target": 1, "grace_seconds": 1, "agent_sources": [ "example" ], "check_spec": { "request": { "headers": { "additionalProperty": "example" }, "secretHeaders": { "additionalProperty": "example" }, "preserveSecretHeaders": true, "secretHeaderNames": [ "example" ], "auth": { "type": "bearer", "token": "example", "username": "example", "password": "example" }, "body": "example", "bodySecret": true, "preserveBody": true, "contentType": "example" }, "assertions": [ { "source": "text_body", "op": "example", "value": "example", "path": "example", "name": "example" } ], "transport": { "payload": "example", "payloadEncoding": "utf8", "expect": "example", "expectMode": "contains", "payloadSecret": true, "preservePayload": true }, "domain": { "warnDays": 1 }, "ping": { "count": 1, "lossDegradedPct": 1, "rttDegradedMs": 1 }, "heartbeat": { "token": "example", "failEnabled": true, "maxDurationSeconds": 1 }, "dns": { "records": [ { "type": "example", "mode": "example", "expected": [ "example" ] } ], "crossCheck": true }, "vendor": { "vendorId": "example", "pageUrl": "example", "probeUrl": "example", "components": [ "example" ] }, "dependencies": [ "example" ] }, "warn_days": 1, "components": [ "example" ], "dependencies": [ "example" ] }'

Authorizations

bearerAuth
write

Parameters

Path Parameters

required

string

Example

mon_123

Request Body

application/json

Partial update: omitted fields keep their current value, EXCEPT check_spec and down_min_sources — see their own field descriptions. Read-only fields return 400, whatever their value: enabled and status (pause and resume with POST /monitors/{id}/pause and POST /monitors/{id}/resume), heartbeat_grace_seconds (send grace_seconds), type (set when the monitor is created), and id, created_at, updated_at. coverage and per_region are read-only too. Any other field is ignored.

object

name

string

target

Up to 2,048 characters. Not used by heartbeat monitors. http: a literal private, loopback or link-local IP (like 192.168.1.10) is accepted only when every location is one of your own agents; with any shared location, or none, it is a 400. tcp and udp: host:port only, port 1 to 65535: no https://, no path, no spaces, and an IPv6 address in square brackets, like [2001:db8::1]:53. icmp (ping): a host name or an IPv4 address, like db.example.com or 192.0.2.10, with no port (ping has none), no https://, no path, no login and no spaces. IPv6 addresses are not supported for ping yet. Anything else is a 400. A target saved before this rule was added keeps working while you leave it unchanged.

string

<= 2048 characters

Example

https://api.example.com/health

interval_seconds

Whole seconds, at most 31,536,000 (365 days), and not below your plan’s fastest check. Anything above the maximum is a 400.

integer

>= 1 <= 31536000

Example

timeout_ms

Max 10000 and less than interval_seconds × 1000.

number

method

Case-insensitive. One of GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS; anything else is a 400.

string

expected_status

Codes like ‘200’, ‘2xx’ or ‘200,301’, up to 128 characters.

string

<= 128 characters

Example

2xx

body_match

Text the response body must contain (case-sensitive, up to 1,024 characters). Only http monitors; the first 1 MiB of the body is searched. Send an empty string or null to clear.

string | null

<= 1024 characters

follow_redirects

Any of:

boolean
number

boolean

down_after_failures

Integer 1..5. Consecutive failed checks before the monitor is marked down. Ignored for heartbeat monitors (still accepted and stored): a heartbeat goes down at the first missed deadline, so use grace_seconds to allow lateness.

number

up_after_successes

Integer 1..5. Consecutive successful checks before a down monitor is marked up again. Ignored for heartbeat monitors (still accepted and stored): a heartbeat is up again at its first ping.

number

down_min_sources

Omitting it (or sending null) resets it to the default quorum. Only applies to monitors that check from agents; for vendor, domain and dns only 1 is accepted.

number | null

sla_target

Percent in (0, 100]. null clears it.

number | null

grace_seconds

Heartbeat only. A whole number of seconds from 1 to 2,592,000 (30 days); anything else is a 400. Extra seconds allowed after the expected ping before it counts as missed. This, not down_after_failures, is how you tolerate a late ping. Defaults to 20% of the interval, at least 60, at most 2,592,000.

integer

>= 1 <= 2592000

agent_sources

Agent ids to probe from. Omit on PATCH to keep the current set.

Array<string>

check_spec

object

request

HTTP monitors: what to send.

object

headers

Plain request headers. Up to 50 headers in total (plain + secret), names up to 256 characters, values up to 8192 characters. The whole check_spec may be at most 128 KB.

object

<= 50 properties

key

additional properties

string

<= 8192 characters

secretHeaders

Write-only. Headers stored encrypted; reads return their names in secretHeaderNames. Send {} to clear. Same limits as headers.

object

<= 50 properties

key

additional properties

string

<= 8192 characters

preserveSecretHeaders

Write-only. true keeps the stored secret headers.

boolean

secretHeaderNames

Read-only. Names of the stored secret headers.

Array<string>

auth

Reads return type only. Send type alone to keep the stored credentials.

object

type

string

Allowed values: bearer basic

token

string

username

string

password

string

body

Request body, up to 65,536 characters.

string

<= 65536 characters

bodySecret

On write, stores body encrypted. On read, true means a secret body is set (it isn’t returned).

boolean

preserveBody

Write-only, with bodySecret: true keeps the stored secret body.

boolean

contentType

string

assertions

HTTP monitors: extra checks on the response.

Array<object>

object

source

string

Allowed values: text_body json_body header response_time cert_expiry

string

value

string

path

Json_body only.

string

name

Header only.

string

transport

TCP and UDP monitors: what to send and expect (the expected reply is the banner check).

object

payload

What to send, up to 1,024 bytes. With payloadEncoding utf8 (the default) these escapes are turned into real characters when the check runs: \r, \n, \t, \xHH (00 to 7F) and \\ for one backslash, so PING\r\n sends PING and a line break. Any other backslash is sent as typed. With hex it is a hex string (0d0a is a line break) and nothing is interpreted.

string

payloadEncoding

string

Allowed values: utf8 hex

expect

string

expectMode

string

Allowed values: contains regex

payloadSecret

On write, stores payload encrypted. On read, true means a secret payload is set.

boolean

preservePayload

Write-only, with payloadSecret: true keeps the stored secret payload.

boolean

domain

Days of warning before a domain or certificate expires.

object

warnDays

integer

ping

ICMP monitors.

object

count

integer

lossDegradedPct

integer

rttDegradedMs

integer

heartbeat

Heartbeat monitors. The server creates the token and keeps it on update.

object

token

The secret in the monitor’s ping URL: https://culipulse.dev/ping/<token> (add /start, /fail, or an exit code such as /0 to the end). Anyone who has it can check the monitor in or mark it down, so it is returned only to tokens with the write scope; with a read-only token it is left out.

string

failEnabled

Always true. /fail, or a check-in with a non-zero exit code (such as /2), always marks the monitor down; that can’t be turned off. A bare ping or /start doesn’t. Sending false is a 400.

boolean

maxDurationSeconds

Run-time limit in seconds, measured from the job’s /start ping to its finishing ping. It only applies to runs that send /start. A run with no finishing ping by the limit is flagged (degraded) at that moment. 0 or omitted means no limit.

integer

dns

DNS monitors.

object

records

Array<object>

object

type

string

mode

string

expected

Array<string>

crossCheck

boolean

vendor

Read-only. Vendor status monitors: set by the server from target.

object

vendorId

string

pageUrl

string

probeUrl

string

components

Array<string>

dependencies

Read-only. Ids of the vendor monitors this monitor depends on.

Array<string>

warn_days

Http: days of warning before the site’s domain expires; 1 or more turns the check on, 0 turns it off. domain: the warning threshold, 1..3650 (default 30). Omit on PATCH to keep the current value.

integer

components

Vendor monitors only: the status-page components to watch. Statuspage vendors: omit or send [] to watch the whole vendor. AWS: service:region targets, at least one. Omit on PATCH to keep the current list.

Array<string>

dependencies

Ids of your vendor monitors this monitor depends on (up to 50); ids that aren’t one of your vendor monitors are ignored. Not allowed on vendor monitors. Omit on PATCH to keep the current list; send [] to clear it.

Array<string>

Responses

200

Updated

application/json

object

required

string

status

required

string

warnings

Present only when the save worked but something will not behave as you might expect, and repeated on every save while it stays true. own_agent_no_secrets: an agent you run is one of the monitor’s locations and the monitor has sign-in details, secret headers, a secret body or a secret payload. Agents you run never receive those, so their checks run without them. Unknown codes may be added later: show message and ignore codes you don’t know.

Array<object>

object

code

required

string

message

required

Plain-language text you can show to a person.

string

Example

{
  "warnings": [
    {
      "code": "own_agent_no_secrets"
    }
  ]
}

400

Invalid request, or the body has a read-only field such as enabled (see MonitorPatch)

application/json

object

error

required

string

request_id

string

code

Present on some 400s so a client can branch without parsing error. Known values: channel_limit_reached, too_many_monitors, duplicate_webhook_url.

string

field

The request field the error is about, when there is one.

string

limit

The limit that was hit, when code names one.

integer

Example

{
  "error": "not found",
  "request_id": "req_abc123",
  "code": "channel_limit_reached"
}

404

Not found

application/json

object

error

required

string

request_id

string

code

Present on some 400s so a client can branch without parsing error. Known values: channel_limit_reached, too_many_monitors, duplicate_webhook_url.

string

field

The request field the error is about, when there is one.

string

limit

The limit that was hit, when code names one.

integer

Example

{
  "error": "not found",
  "request_id": "req_abc123",
  "code": "channel_limit_reached"
}