REST API Endpoints for Monitor Management

Create, read, update, delete, and trigger monitors via the PulseGuard REST API. Requires a valid API key.

The Monitors API gives you complete lifecycle control over every monitor in your account. Use it to automate monitor provisioning in CI/CD pipelines, sync monitor configuration from infrastructure-as-code, tail live check results, or force immediate health checks during deployments. All endpoints require a valid Bearer token. Endpoints that create, update, or delete resources additionally enforce the write scope and return 403 if it is absent.

---

List all monitors

Retrieve every monitor belonging to your account, ordered by creation date descending.

GET /api/cli/monitors

Request headers

Header	Value
Authorization	Bearer <api_key>

curl example

curl https://app.pulseguard.io/api/cli/monitors \
  -H "Authorization: Bearer pg_live_your_api_key"

Response

{
  "monitors": [
    {
      "id": "clx1234abc",
      "name": "Production API",
      "url": "https://api.example.com/health",
      "type": "HTTP",
      "status": "UP",
      "interval": 60,
      "timeout": 10,
      "lastCheck": "2024-01-15T10:30:00.000Z",
      "nextCheck": "2024-01-15T10:31:00.000Z",
      "alertThreshold": 1,
      "checkRegions": null,
      "method": "GET"
    }
  ]
}

Show Response fields

monitors · array · required

Array of monitor objects.

monitors[].id · string · required

Unique identifier for the monitor.

monitors[].name · string · required

Human-readable name you gave the monitor.

monitors[].url · string · required

The URL being monitored.

monitors[].type · string · required

Monitor type. Currently HTTP.

monitors[].status · string · required

Current status: UP, DOWN, or PENDING.

monitors[].interval · integer · required

Check interval in seconds.

monitors[].timeout · integer · required

Request timeout in seconds.

monitors[].lastCheck · string

ISO 8601 timestamp of the last completed check. null if the monitor has never been checked.

monitors[].nextCheck · string

ISO 8601 timestamp of the next scheduled check.

monitors[].alertThreshold · integer · required

Number of consecutive failures before an alert fires.

monitors[].checkRegions · string | null

JSON-encoded array of region codes, or null to use the default region.

monitors[].method · string · required

HTTP method used for checks (e.g. GET, POST).

---

Create a monitor

Create a new HTTP monitor. Requires the write scope.

POST /api/cli/monitors

Request headers

Header	Value
Authorization	Bearer <api_key> (write scope required)
Content-Type	application/json

Request body

name · string · required

Display name for the monitor. Cannot be blank.

url · string · required

The full URL to monitor, including the scheme (e.g. https://api.example.com/health). Cannot be blank.

type · string · default: "HTTP"

Monitor type. Currently only HTTP is supported.

interval · integer · default: "60"

How often to run the check, in seconds.

timeout · integer · default: "10"

Maximum time to wait for a response, in seconds. A check that exceeds this limit is recorded as TIMEOUT.

method · string · default: "GET"

HTTP method to use: GET, POST, PUT, PATCH, or HEAD.

headers · object

Custom request headers sent with each check. Provide as a key-value object, e.g. {"X-Api-Version": "2"}. Stored as JSON.

body · string

Request body to send with POST, PUT, or PATCH checks.

expectation · object

Assertion rules that must pass for a check to be considered UP. Stored as JSON. Example: {"statusCode": 200, "bodyContains": "ok"}.

alertThreshold · integer · default: "1"

Number of consecutive failures required before an alert is triggered.

checkRegions · array

List of region codes to run checks from, e.g. ["us-east-1", "eu-west-1"]. Leave empty to use the default region.

runbookUrl · string

URL of the runbook or incident-response guide for this monitor. Included in alert notifications and webhook payloads.

curl example

curl -X POST https://app.pulseguard.io/api/cli/monitors \
  -H "Authorization: Bearer pg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "url": "https://api.example.com/health",
    "interval": 60,
    "timeout": 10,
    "method": "GET",
    "alertThreshold": 2,
    "runbookUrl": "https://docs.example.com/runbooks/api"
  }'

Response 201 Created

{
  "monitor": {
    "id": "clx1234abc",
    "name": "Production API",
    "url": "https://api.example.com/health",
    "type": "HTTP",
    "status": "PENDING",
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
}

A newly created monitor has status: "PENDING" until the first check completes. Use the trigger endpoint to run the first check immediately.

---

Get a monitor

Retrieve full details of a single monitor, including its 10 most recent check events.

GET /api/cli/monitors/:id

curl example

curl https://app.pulseguard.io/api/cli/monitors/clx1234abc \
  -H "Authorization: Bearer pg_live_your_api_key"

Response

{
  "monitor": {
    "id": "clx1234abc",
    "name": "Production API",
    "url": "https://api.example.com/health",
    "type": "HTTP",
    "status": "UP",
    "interval": 60,
    "timeout": 10,
    "method": "GET",
    "headers": null,
    "body": null,
    "expectation": null,
    "alertThreshold": 1,
    "checkRegions": null,
    "runbookUrl": "https://docs.example.com/runbooks/api",
    "lastCheck": "2024-01-15T10:30:00.000Z",
    "nextCheck": "2024-01-15T10:31:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "events": [
      {
        "status": "UP",
        "latency": 245,
        "errorReason": null,
        "timestamp": "2024-01-15T10:30:00.000Z",
        "region": "us-east-1"
      }
    ]
  }
}

Returns 404 if the monitor ID does not exist or belongs to a different account.

---

Update a monitor

Update one or more fields on an existing monitor. Only fields you include in the request body are changed — omitted fields remain unchanged. Requires the write scope.

PUT /api/cli/monitors/:id

Request headers

Header	Value
Authorization	Bearer <api_key> (write scope required)
Content-Type	application/json

Request body

All fields are optional. Provide only the fields you want to update.

name · string

New display name.

url · string

New URL to monitor.

interval · integer

New check interval in seconds.

timeout · integer

New request timeout in seconds.

method · string

New HTTP method.

alertThreshold · integer

New consecutive-failure threshold for alerts.

runbookUrl · string

New runbook URL.

headers · object

Replacement custom headers object. Overwrites any previously stored headers.

expectation · object

Replacement assertion rules. Overwrites any previously stored expectation.

checkRegions · array

Replacement list of region codes.

curl example

curl -X PUT https://app.pulseguard.io/api/cli/monitors/clx1234abc \
  -H "Authorization: Bearer pg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "interval": 30,
    "alertThreshold": 3
  }'

Response

{
  "monitor": {
    "id": "clx1234abc",
    "name": "Production API",
    "url": "https://api.example.com/health",
    "type": "HTTP",
    "status": "UP",
    "updatedAt": "2024-01-15T11:00:00.000Z"
  }
}

---

Delete a monitor

Permanently delete a monitor and all its associated events. This action cannot be undone. Requires the write scope.

DELETE /api/cli/monitors/:id

curl example

curl -X DELETE https://app.pulseguard.io/api/cli/monitors/clx1234abc \
  -H "Authorization: Bearer pg_live_your_api_key"

Response

{
  "success": true
}

Deleting a monitor permanently removes all historical check events and incidents associated with it. Export any data you need before deleting.

---

Trigger an immediate check

Force an HTTP health check on a monitor right now, bypassing the normal schedule. The check runs synchronously and returns the result in the response. The result is also persisted as a regular monitor event. Any valid Bearer token can trigger this endpoint; providing a URL override additionally requires the write scope.

POST /api/cli/monitors/:id/trigger

Request headers

Header	Value
Authorization	Bearer <api_key>
Content-Type	application/json (only if using URL override)

Optional request body

url · string

Override the monitor’s configured URL for this single check. Useful for testing a new endpoint before updating the monitor. Requires the write scope.

curl example

# Standard trigger — no body required
curl -X POST https://app.pulseguard.io/api/cli/monitors/clx1234abc/trigger \
  -H "Authorization: Bearer pg_live_your_api_key"

# With a URL override (write scope required)
curl -X POST https://app.pulseguard.io/api/cli/monitors/clx1234abc/trigger \
  -H "Authorization: Bearer pg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.example.com/health/v2"}'

Response

{
  "monitorId": "clx1234abc",
  "name": "Production API",
  "url": "https://api.example.com/health",
  "status": "UP",
  "latency": 182,
  "httpStatus": 200,
  "errorReason": null,
  "checkedAt": "2024-01-15T10:30:00.000Z"
}

Show Response fields

monitorId · string · required

ID of the monitor that was checked.

name · string · required

Display name of the monitor.

url · string · required

The URL that was actually checked (may differ from the monitor’s configured URL if an override was provided).

status · string · required

Result of the check: UP or DOWN.

latency · integer · required

Round-trip time in milliseconds.

httpStatus · integer

HTTP status code returned by the target. null if the request did not complete.

errorReason · string | null · required

Machine-readable failure reason if status is DOWN. Possible values: TIMEOUT, DNS_ERROR, CONNECTION_REFUSED, HTTP_<code> (e.g. HTTP_503), UNKNOWN_ERROR. null when status is UP.

checkedAt · string · required

ISO 8601 timestamp of when the check was performed.

The trigger endpoint only supports HTTP monitors. Attempting to trigger a monitor of another type returns 422 Unprocessable Entity.

---

List monitor events

Retrieve the check history for a monitor in chronological order. Supports incremental polling with the since parameter — ideal for building live log tails.

GET /api/cli/monitors/:id/events

Query parameters

limit · integer · default: "50"

Maximum number of events to return. The server caps this at 500.

since · string

ISO 8601 timestamp. When provided, only events recorded after this timestamp are returned. Use the timestamp of the last event you received to poll incrementally.

curl example

# Fetch the 50 most recent events
curl "https://app.pulseguard.io/api/cli/monitors/clx1234abc/events" \
  -H "Authorization: Bearer pg_live_your_api_key"

# Poll for events since the last one you received
curl "https://app.pulseguard.io/api/cli/monitors/clx1234abc/events?since=2024-01-15T10:30:00.000Z" \
  -H "Authorization: Bearer pg_live_your_api_key"

Response

{
  "monitorId": "clx1234abc",
  "name": "Production API",
  "events": [
    {
      "id": "evt_abc123",
      "status": "UP",
      "latency": 245,
      "errorReason": null,
      "timestamp": "2024-01-15T10:30:00.000Z",
      "region": "us-east-1"
    },
    {
      "id": "evt_def456",
      "status": "DOWN",
      "latency": 10002,
      "errorReason": "TIMEOUT",
      "timestamp": "2024-01-15T10:29:00.000Z",
      "region": "us-east-1"
    }
  ]
}

Show Response fields

monitorId · string · required

ID of the monitor.

name · string · required

Display name of the monitor.

events · array · required

Events in chronological (oldest-first) order.

events[].id · string · required

Unique event identifier.

events[].status · string · required

UP or DOWN.

events[].latency · integer · required

Round-trip time in milliseconds.

events[].errorReason · string | null · required

Failure reason for DOWN events. null for UP events.

events[].timestamp · string · required

ISO 8601 timestamp of the check.

events[].region · string · required

Region code that performed the check (e.g. us-east-1, cli-trigger).