Developer overview

SutramX gives developers several ways to automate monitoring, react to alerts and connect SutramX to other systems. This page explains each one and helps you choose. Most of them use an API key, which you create in Account settings → API keys.

At a glance#

API keys#

The REST API and every developer tool built on it authenticate with an API key. Keys:

• Belong to one workspace and act on that workspace only.
• Can only be created and deleted by the workspace owner, in Account settings → API keys.
• Start with sk_ and are shown once, when you create them.
• Have a read-only, standard or automation access level. Read-only keys (the dashboard default) can read but change nothing. Standard keys act like a workspace member. Automation keys can also manage alert channels and the OpenTelemetry export.
• Never have access to billing, team management, other API keys or account settings.

API keys are included on paid plans, and the number of keys depends on your plan. See Plans & limits. The REST API guide walks through creating a key.

REST API#

The REST API is the foundation for everything else. It covers monitors and monitor groups, check history and stats, incidents and notes, status pages, alert channels, deploy events, reliability features and more.

curl -s "https://api.sutramx.com/monitors" \
  -H "Authorization: Bearer $SUTRAMX_API_KEY"

Choose the REST API when you want to:

• Create monitors automatically when you launch a new service or customer environment.
• Pause monitors around a deploy and resume them afterwards.
• Pull uptime and incident data into your own dashboards or reports.
• Acknowledge or resolve incidents from your own tooling.

Start with the REST API guide, then look up endpoints in the API reference. You can also see the base URL and a short endpoint list on the API documentation tab of Alerts → Channels & API.

Webhooks#

A webhook alert channel sends a signed JSON request to your endpoint for each alert event. It doesn't need an API key: you add the endpoint as an alert channel in Alerts → Channels & API, and SutramX calls it.

Choose webhooks when you want SutramX to push events to you, for example to open tickets, post to an internal chat tool, or trigger automatic remediation. See Webhooks for the events, payload and signature check.

Heartbeat URLs#

A heartbeat (cron) monitor gives you a unique URL. Your job calls it each time it runs, and SutramX alerts you when a run is missed or reports a failure. The token in the URL is the credential, so no API key is needed.

0 3 * * * /usr/local/bin/backup.sh && curl -fsS "https://api.sutramx.com/heartbeat/<token>"

See Heartbeat & cron.

Deploy events#

Recording deployments lets SutramX show which deploy came before an incident. You can send them from GitHub or GitLab through a signed webhook, or from any CI system with POST /incidents/deploy-events. Deploy events need a plan that includes deployment correlation. See Deployment correlation.

CLI and monitors as code#

The sutramx CLI lets you list and change monitors from the terminal, and describe monitors in a sutramx.yml file that you review with a plan and apply, like infrastructure as code. See CLI & monitors as code.

The CLI is built on monitoring-as-code endpoints you can also call directly: PUT /automation/monitors/:key creates or updates one monitor by a key you choose, and POST /automation/monitors/plan and /apply work on a whole list. See Monitoring as code.

GitHub Action#

The GitHub Action runs the CLI in your workflows, so you can plan monitor changes in pull requests and apply them after merging. See GitHub Action.

Terraform provider#

The Terraform provider (sutramx/sutramx on the Terraform Registry) lets you manage SutramX monitors, status pages and alert channels alongside the infrastructure they watch. Managing alert channels needs an API key with automation access. See Terraform provider.

MCP server#

The MCP server lets AI assistants and coding agents that support the Model Context Protocol check monitor status, look at incidents and make changes, using your API key. See MCP server for AI tools.

OpenTelemetry export#

The OpenTelemetry export will send each check result to your own collector as a span, so you can view SutramX checks in the same tool as your application traces. See OpenTelemetry export.

Which should I use?#

Common questions#

Do I need a paid plan to use the API?#

API keys are included on paid plans. Webhooks, heartbeat URLs and public status page feeds don't need an API key, but some of them depend on your plan too. See Plans & limits.

Can team members create API keys?#

No. Only the workspace owner can create or delete keys. Members can see the list of keys.

Is there an SDK?#

There is no official SDK yet. The API is plain JSON over HTTPS, so any HTTP client works.