New: Connect AI assistants via MCP

Core Concepts

API Monitoring

API Monitoring (JSON Response Assertions)

API monitoring verifies that an endpoint returns the correct response body, not just a successful HTTP status. After a request succeeds, the system evaluates JSON assertions against the response payload — so a 200 OK that returns an error flag, a missing field, or a stale value is still caught and flagged as an outage.

Use Cases

  • Health-check endpoints - Assert data.status equals "ok" on a custom /health route
  • API contract monitoring - Verify a REST endpoint still returns the structure your app depends on
  • Third-party integrations - Detect when a partner API starts returning errors inside a 200 response
  • Authenticated & write endpoints - Send custom headers and a request body to monitor POST/PUT routes
  • Data sanity checks - Alert when a queue depth, inventory count, or balance crosses a threshold

How It Works

During each check, the system:

  1. Sends the request using your monitor's method, headers, body and timeout settings
  2. Confirms the HTTP status is within the accepted status codes
  3. Parses the JSON response body and evaluates every configured assertion
  4. Marks the monitor offline and opens a json_assertion incident if any assertion fails
  5. Sends notifications to your configured channels, then auto-resolves when all assertions pass again

Setting Up API Monitoring

  1. Enable the "JSON" check type when creating or editing a monitor
  2. Set the HTTP method, request headers and request body if the endpoint needs them
  3. Add up to 10 assertions, each with a path, operator and (where required) an expected value
  4. Save the monitor — assertions are evaluated on the next and every subsequent check

The JSON and Keyword check types are mutually exclusive on a single monitor — a response is either an API payload or a web page. Use separate monitors if you need both.

Assertion Paths

Each assertion targets a value in the response with a dot-notation path. Use numeric segments to index into arrays.

Path Selects
status The top-level status field
data.region The region field nested inside data
data.users.0.id The id of the first item in the users array

Operators

Operator Passes when Value
equals The value at the path equals the expected value Required
not_equals The value does not equal the expected value Required
contains The value contains the expected substring Required
not_contains The value does not contain the expected substring Required
exists The path is present in the response Not used
not_exists The path is absent from the response Not used
gt / gte The value is greater than / greater than or equal to the expected number Required
lt / lte The value is less than / less than or equal to the expected number Required
regex The value matches the expected regular expression Required
not_regex The value does not match the expected regular expression Required

Request Options

API monitors reuse the monitor's HTTP request settings, so you can monitor endpoints that need a specific method, authentication or payload:

Option Description
http_method GET, POST, PUT, PATCH, DELETE, HEAD or OPTIONS
request_headers Custom headers, e.g. an Authorization token
request_body A JSON or form body sent with POST, PUT and PATCH requests
accepted_status_codes Which status codes count as success before assertions run

Limits

  • Maximum 10 assertions per monitor
  • Each assertion path can be up to 500 characters
  • Response bodies larger than 5 MB are not evaluated
  • Assertions run only when the response is valid JSON and the status code is accepted

Notifications

When an assertion fails, the incident is classified as a JSON assertion failure rather than a generic outage. Notifications include:

  • The failing path, the operator, the expected value and the actual value
  • The monitor URL and the region that detected the failure

A recovery notification is sent once every assertion passes again, including the incident duration.

Best Practices

  • Assert on stable fields - Target contract fields that should not change between deploys
  • Prefer a health endpoint - Expose a dedicated /health route that summarises dependencies
  • Combine operators - Pair exists checks with equals or numeric thresholds
  • Watch dependencies - Assert that database, queue or cache status fields report healthy
  • Keep paths shallow - Shallow paths are more resilient to response shape changes

Example Configuration

{
  "assertions": [
    {
      "path": "data.status",
      "operator": "equals",
      "value": "ok"
    },
    {
      "path": "data.region",
      "operator": "exists"
    },
    {
      "path": "data.queue.depth",
      "operator": "lt",
      "value": 1000
    }
  ]
}
Keyword MonitoringPing Monitoring