REST API Endpoints for Monitor Management

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

array

required

Array of monitor objects.

string

required

Unique identifier for the monitor.

string

required

Human-readable name you gave the monitor.

string

required

The URL being monitored.

string

required

Monitor type. Currently HTTP.

string

required

Current status: UP, DOWN, or PENDING.

integer

required

Check interval in seconds.

integer

required

Request timeout in seconds.

string

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

string

ISO 8601 timestamp of the next scheduled check.

integer

required

Number of consecutive failures before an alert fires.

string | null

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

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

string

required

Display name for the monitor. Cannot be blank.

string

required

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

string

default:"HTTP"

Monitor type. Currently only HTTP is supported.

integer

default:"60"

How often to run the check, in seconds.

integer

default:"10"

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

string

default:"GET"

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

object

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

string

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

object

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

integer

default:"1"

Number of consecutive failures required before an alert is triggered.

array

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

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.

string

New display name.

string

New URL to monitor.

integer

New check interval in seconds.

integer

New request timeout in seconds.

string

New HTTP method.

integer

New consecutive-failure threshold for alerts.

string

New runbook URL.

object

Replacement custom headers object. Overwrites any previously stored headers.

object

Replacement assertion rules. Overwrites any previously stored expectation.

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

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

string

required

ID of the monitor that was checked.

string

required

Display name of the monitor.

string

required

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

string

required

Result of the check: UP or DOWN.

integer

required

Round-trip time in milliseconds.

integer

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

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.

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

integer

default:"50"

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

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

string

required

ID of the monitor.

string

required

Display name of the monitor.

array

required

Events in chronological (oldest-first) order.

string

required

Unique event identifier.

string

required

UP or DOWN.

integer

required

Round-trip time in milliseconds.

string | null

required

Failure reason for DOWN events. null for UP events.

string

required

ISO 8601 timestamp of the check.

string

required

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

​List all monitors

​Request headers

​curl example

​Response

​Create a monitor

​Request headers

​Request body

​curl example

​Response 201 Created

​Get a monitor

​curl example

​Response

​Update a monitor

​Request headers

​Request body

​curl example

​Response

​Delete a monitor

​curl example

​Response

​Trigger an immediate check

​Request headers

​Optional request body

​curl example

​Response

​List monitor events

​Query parameters

​curl example

​Response

List all monitors

Request headers

curl example

Response

Create a monitor

Request headers

Request body

curl example

Response `201 Created`

Get a monitor

curl example

Response

Update a monitor

Request headers

Request body

curl example

Response

Delete a monitor

curl example

Response

Trigger an immediate check

Request headers

Optional request body

curl example

Response

List monitor events

Query parameters

curl example

Response