API reference

This reference lists the endpoints you can call with a SutramX API key, grouped by resource. For authentication, rate limits, pagination and the error format, read the REST API guide first.

All paths are relative to https://api.sutramx.com. Every request needs Authorization: Bearer sk_... unless it is marked as public. IDs are UUIDs.

The Access column uses these labels:

• Any key: GET requests work with every key, including read-only keys. Requests that change something (POST, PUT, PATCH, DELETE) need a Standard or Automation key; a read-only key gets 403 READ_ONLY_ACCESS.
• Automation key: needs a key created with the Automation access level.
• Owner only: needs the workspace owner's dashboard session. API keys get 403 WORKSPACE_OWNER_REQUIRED.
• Plan: also needs a plan that includes the feature. Otherwise you get 403 FEATURE_NOT_AVAILABLE. See Plans & limits.

Endpoints not listed here (team members, billing, API keys, workspace settings, alert routing defaults) need a signed-in dashboard session and reject API keys.

Monitors#

Create a monitor#

POST /monitors

curl -s -X POST "https://api.sutramx.com/monitors" \
  -H "Authorization: Bearer $SUTRAMX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout API",
    "type": "http",
    "url": "https://api.example.com/health",
    "interval_seconds": 60,
    "regions": ["fra1", "usa-az-probe"],
    "tags": ["checkout", "prod"],
    "config": {
      "method": "GET",
      "timeout": 10000,
      "expected_status_codes": [200],
      "keyword": "ok"
    }
  }'

The response is 201 with the new monitor. An abridged example:

{
  "id": "6f1c2a7e-3b0d-4c8e-9f51-2d7a9b1e4c10",
  "name": "Checkout API",
  "type": "http",
  "url": "https://api.example.com/health",
  "interval_seconds": 60,
  "is_active": true,
  "group_id": null,
  "tags": ["checkout", "prod"],
  "config": { "method": "GET", "timeout": 10000, "expected_status_codes": [200], "keyword": "ok" },
  "created_at": "2026-10-02T08:15:00.000Z"
}

The workspace owner's email must be verified before monitors can be created (403 EMAIL_VERIFICATION_REQUIRED). Creating a monitor over your plan's monitor limit returns 403 ENTITLEMENT_LIMIT_REACHED.

Monitor object#

GET /monitors and GET /monitors/:id return monitors with these computed fields in addition to the stored ones:

Update a monitor#

PUT /monitors/:id accepts name, url, interval_seconds, is_active, group_id, escalation_policy_id, config and tags, with the same limits as create. You can't change type; create a new monitor instead. To change regions, use PUT /monitors/:id/regions.

Monitor config#

The config object holds type-specific settings. It can have up to 50 keys and must be at most 32 KB as JSON. The most common keys:

The full set of options for each type, including DNS and multi-step checks, is described on the monitor pages: HTTP & keyword, API & multi-step checks, Ping, TCP & UDP, DNS and Heartbeat & cron.

config.notification_emails (per-monitor alert recipients) changes where alerts go. When sent with an API key on POST /monitors or PUT /monitors/:id, it is ignored. An automation key can set it through monitoring as code; other keys get 403 ALERT_ROUTING_NOT_ALLOWED there.

Bulk actions#

POST /monitors/bulk

{ "updated": 12, "failed": [{ "id": "…", "error": "Monitor not found" }] }

Check history#

GET /monitors/:id/checks

{
  "items": [
    {
      "id": "b3f0…",
      "checked_at": "2026-10-02T08:20:00.412873Z",
      "region": "fra1",
      "status": "up",
      "status_code": 200,
      "response_time_ms": 182,
      "error_type": null,
      "error_message": null
    }
  ],
  "next_before": "2026-10-02T08:20:00.412873Z"
}

Check timestamps have microsecond precision.

GET /monitors/:id/checks.csv accepts from, to (ISO 8601), region and status. If the range has more than 50,000 rows, the newest rows are returned and the X-Export-Truncated: true header is set.

Regions#

PUT /monitors/:id/regions takes { "regions": ["fra1", "usa-az-probe"] } (1–50 region codes). The regions you can use depend on your plan. See Regions & confirmation.

Test notification#

POST /monitors/:id/test-notification sends a test alert email. The optional email field must be one of the monitor's alert recipients or a workspace member. Without it, the first recipient is used.

Cron heartbeats#

For cron jobs, the simplest option is the monitor's public heartbeat_url, which needs no API key. See Heartbeats.

POST /monitors/:id/cron-heartbeat records a heartbeat with your API key instead. All fields are optional:

Heartbeats#

GET, POST or HEAD /heartbeat/:token is public: the token in the URL is the credential. Copy the URL from the monitor's heartbeat_url.

The response is 200 with the text OK (also for a paused monitor, whose pings are ignored), 404 for an unknown token, and 400 for a bad parameter. Any request body is ignored.

curl -fsS "https://api.sutramx.com/heartbeat/$HEARTBEAT_TOKEN?duration_ms=5230"

Monitor groups#

Stats#

All stats endpoints take a monitor ID and are limited to 1,000 requests per minute. Uptime history goes back 365 days on Starter and 730 days on Growth and Pro. timeZone takes an IANA zone such as Asia/Kolkata.

{
  "uptime_percentage": 99.95,
  "total_checks": 43200,
  "successful_checks": 43178,
  "failed_checks": 22,
  "avg_response_time_ms": 214
}

Incidents#

List incidents#

GET /incidents

{
  "items": [
    {
      "id": "0c9e…",
      "monitor_id": "6f1c…",
      "monitor_name": "Checkout API",
      "monitor_url": "https://api.example.com/health",
      "monitor_type": "http",
      "started_at": "2026-10-01T22:04:10.000Z",
      "resolved_at": "2026-10-01T22:11:40.000Z",
      "duration_seconds": 450,
      "alert_suppressed": false,
      "suppression_reason": null,
      "is_flapping": false,
      "confirmations": 2,
      "confirming_regions": ["fra1", "usa-az-probe"],
      "confirming_region_names": ["FRA1 (Frankfurt, Germany)", "AZ (Arizona, USA)"],
      "regions_total": 2,
      "acknowledged_at": null,
      "acknowledged_by_name": null,
      "snoozed_until": null,
      "resolved_manually": false,
      "github_issue_url": null
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 25,
  "counts": { "all": 1, "ongoing": 0, "resolved": 1, "suppressed": 0 }
}

Incident request bodies#

Runbooks#

Deploy events#

Deploy events need a plan with deployment correlation (Plan). See Deployment correlation.

GitHub and GitLab deploy payloads must go to your signed deploy webhook URL, not this endpoint. Sending source: "github" or "gitlab" here returns 400 USE_SIGNED_DEPLOY_HOOK.

Maintenance windows#

Creating, editing and deleting maintenance windows silences alerts, so it is owner-only and can't be done with an API key. See Maintenance windows.

Status pages#

Creating and changing status pages needs a plan that includes status pages (Plan).

Create and update fields#

POST /status/pages accepts title (required, 1–255 characters), description (up to 1,000 characters or null) and is_public (boolean).

PATCH /status/pages/:id accepts any of these. Unknown fields are rejected.

PUT /status/pages/:id/monitors takes { "monitors": [{ "monitor_id": "…", "section": "API" }] } with up to 500 entries. section is optional (up to 100 characters). POST /status/pages/:id/monitors takes { "monitorId": "…", "section": "API" }.

Access and language settings, and their plan requirements, are covered in Private pages & SSO and Branding & custom domains. Custom domains are owner-only.

Public status page endpoints#

These endpoints are public (no key) and limited to 60 requests per minute per IP. :slug is the page's slug.

Alert channels#

Alert channels (Slack, Microsoft Teams, Discord, webhooks, PagerDuty, Opsgenie, GitHub and others) are called integrations in the API. Each channel type can have up to 10 connections.

Connection body#

The body has the channel's fields at the top level, plus optional name and routing:

curl -s -X POST "https://api.sutramx.com/integrations/slack/connections" \
  -H "Authorization: Bearer $SUTRAMX_AUTOMATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "#ops-alerts",
    "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX",
    "routing": { "scope": "all", "min_severity": "down" }
  }'

{
  "success": true,
  "message": "#ops-alerts connected",
  "connection_id": "1d2e…",
  "name": "#ops-alerts",
  "integration_type": "slack",
  "auto_test": true
}

A new webhook connection also returns signing_secret once. Store it to verify deliveries. See Webhooks.

Whether a channel type is available depends on your plan (403 FEATURE_NOT_AVAILABLE otherwise). SMS, WhatsApp and voice alerts use alert credits. See Alert credits.

Alert recipients#

Adding and removing recipients is owner-only. See Email & push.

Alerting settings (read-only)#

API keys can read, but not change, the workspace's alerting setup:

The team member list (/team/members) is not available to API keys.

Reliability#

Add a dependency (POST /reliability/dependencies): parent_monitor_id (UUID, required), child_monitor_id (UUID, required) and suppression_mode (optional, suppress_child_if_parent_down).

SLO target (POST /reliability/slo-targets):

Website health#

Website health needs a plan that includes it.

See Website health for what each run checks.

Third-party status#

Subscription fields: provider_id (required on create, up to 60 characters), component_ids (up to 200), keywords (up to 20, each up to 60 characters), notify (boolean), notify_maintenance (boolean) and min_severity (minor, major or critical). Following providers needs a plan that includes third-party status. See Third-party status.

AI incident assist#

These endpoints need a plan that includes the AI features, and each generation counts toward your monthly AI allowance. Generations are limited to 30 per 10 minutes per workspace.

See AI incident assist.

Monitoring as code#

These endpoints manage monitors by a stable key you choose, so a config file or script can create a monitor the first time and update it on every later run. A key is 1–128 characters: letters, digits and . _ : / -, starting with a letter or digit.

A monitor spec has the same fields as POST /monitors (except group_id and escalation_policy_id), plus key, paused (boolean) and regions (null resets to your plan's default regions). Fields you leave out aren't managed: an existing monitor keeps its value. Changing type replaces the monitor (its history is deleted); on apply, that needs the plan confirmation described below.

curl -s -X PUT "https://api.sutramx.com/automation/monitors/checkout-api" \
  -H "Authorization: Bearer $SUTRAMX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Checkout API", "type": "http", "url": "https://api.example.com/health", "interval_seconds": 60 }'

plan and apply take this body (up to 2 MB):

plan returns changes (each with action: create, update, replace, delete or noop), a summary, warnings and a plan_fingerprint. apply returns ok, summary, per-monitor results and plan_fingerprint, with status 207 if some changes failed. An apply that would delete or replace monitors needs expected_fingerprint or allow_prune_without_fingerprint; otherwise it returns 428 PRUNE_CONFIRMATION_REQUIRED and changes nothing.

{
  "workspace_id": "a71c…",
  "user_email": "owner@example.com",
  "auth_type": "api_key",
  "api_key_access": "standard",
  "workspace_role": "member",
  "read_only": false,
  "can_manage_alert_channels": false,
  "plan": "growth",
  "market": "global",
  "limits": { "monitors": 200, "min_interval_seconds": 30, "probe_locations": 5, "status_pages": 10 }
}

The example above is a whoami response with illustrative values. The plan and limits you see are your own.

OpenTelemetry export#

OpenTelemetry export isn't generally available yet. The fields are described in GitHub, OTel & more.