canonical: https://jentic.com/apis/betterstack.com/betterstack

# Better Stack Uptime API

Jentic publishes the only available OpenAPI specification for Better Stack Uptime API, keeping it validated and agent-ready. The Better Stack Uptime API follows the JSON:API specification and allows engineering teams to manage HTTP and TCP monitors, cron and worker heartbeats, incidents, and public status pages. It powers SRE-facing automation such as creating monitors when new services deploy, resolving incidents from chat ops, and pulling availability and response-time metrics for SLO reporting. The spec covers 20 endpoints scoped to v2.

## For AI agents

Manage uptime monitors, heartbeats, incidents, and status pages on Better Stack. Pull response time and availability metrics for SLO reporting.

## Scope

Does not handle log ingestion, application metrics, or distributed tracing - use for Better Stack uptime monitors, heartbeats, incidents, and status pages only.

## Capabilities

- Create and manage HTTP and TCP uptime monitors
- Register cron and worker heartbeats and detect missed runs
- Track incidents and programmatically resolve them
- Create and update public status pages
- Retrieve response time samples for a monitor over a time window
- Pull availability percentages for SLO reporting

## Use cases

### Auto-Provisioning Service Monitors

When a new service deploys to production, automatically create matching uptime monitors so the on-call team has visibility from minute one. POST /monitors takes the URL, expected status code, and check interval, and returns the monitor id for tagging in the deployment metadata. Wiring this into a deploy pipeline is typically half a day of work.

Example prompt: On deploy, POST /monitors with the new service URL and 30-second check interval, then store the returned monitor_id alongside the service record

### Cron Job Heartbeat Tracking

Use heartbeats to confirm that scheduled jobs ran on time. POST /heartbeats registers a heartbeat with an expected interval, and the job's runner pings the heartbeat URL each run. `/heartbeats/{heartbeat_id}` returns missed-run state for alerting. Setting up heartbeats for a fleet of cron jobs takes a few hours and immediately exposes silent failures.

Example prompt: POST /heartbeats with name and 60-minute period, then update the cron config to ping the returned heartbeat URL on each successful run

### Chat-Ops Incident Resolution

Let engineers resolve Better Stack incidents from chat without context-switching to the dashboard. /incidents lists open incidents and POST `/incidents/{incident_id}/resolve` marks one resolved. Combined with a status page update via PATCH `/status-pages/{status_page_id}`, an on-call engineer can clear an outage in two API calls from the chat interface.

Example prompt: GET /incidents to list open issues, then POST `/incidents/{incident_id}/resolve` for the one named in the chat command and patch the status page

### AI Agent for SRE Operations

An AI agent uses Jentic to discover Better Stack operations and assist on-call engineers: provisioning monitors, summarising open incidents, or pulling availability for an SLO report. The agent searches by intent, loads the operation schema, and executes against Better Stack without browsing the 20-endpoint reference. Through Jentic, integration takes under an hour.

Example prompt: Search Jentic for 'list open betterstack incidents' and execute /incidents, then summarise top 3 incidents by severity in the on-call channel

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/monitors` | Create an uptime monitor |
| GET | `/monitors/{monitor_id}/response-times` | Response time history for a monitor |
| GET | `/monitors/{monitor_id}/availability` | Availability percentage over a time window |
| POST | `/heartbeats` | Register a heartbeat |
| GET | `/incidents` | List incidents |
| POST | `/incidents/{incident_id}/resolve` | Resolve an incident |
| POST | `/status-pages` | Create a status page |
| PATCH | `/status-pages/{status_page_id}` | Update a status page |

## Key resources

- **Monitors** — HTTP and TCP uptime monitors with response time and availability metrics
- **Heartbeats** — Cron and worker heartbeats that fire alerts when expected pings are missed
- **Incidents** — Open and historical incidents with explicit resolve action
- **Status Pages** — Public-facing status pages aggregating monitors and components

## Why Jentic

- **Setup:** Wiring the Better Stack Uptime API by hand means learning its bearer auth, tracking monitor, incident, and status-page ids across calls, and handling paging yourself. Through Jentic you install once, import Better Stack from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Better Stack puts the monitor id in the URL path (`/monitors/{monitor_id}/...`), so a rule can pin your agent to one monitor: it can read that monitor's availability and response times and nothing else. You choose the operations it may call, so incident-resolving or status-page changes are not included unless you add them.
- **Credential handling:** Your Better Stack bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an uptime monitor' or 'resolve an incident', and Jentic returns the matching Better Stack operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **PagerDuty API** — On-call routing for Better Stack incidents into the right responder
- **Statuspage API** — Atlassian's public status page product as an alternative to Better Stack status pages

## FAQ

### Why is there no official OpenAPI spec for Better Stack Uptime API?

Better Stack publishes JSON:API documentation rather than an OpenAPI specification. Jentic generates and maintains this OpenAPI spec so that AI agents and developers can call Better Stack Uptime API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Better Stack Uptime API use?

The Better Stack Uptime API uses HTTP Bearer authentication - clients send Authorization: Bearer <token> on every request, where the token comes from the Better Stack team API tokens page. When called via Jentic, the token is stored encrypted in your Jentic One instance and injected at execution time so it never appears in the agent's context.

### Can I resolve an incident programmatically?

Yes. POST `/incidents/{incident_id}/resolve` marks the incident resolved without further input. GET /incidents lists current incidents, and GET `/incidents/{incident_id}` returns the full timeline so a chat-ops or runbook integration can present context before resolving.

### How do I create a heartbeat through Jentic?

Run pip install jentic and search for 'create betterstack heartbeat'. Jentic returns POST /heartbeats, the agent loads the schema, and executes with name and expected period. Use the returned heartbeat URL as the ping target in your scheduled job runner.

### What rate limits apply to the Better Stack Uptime API?

Better Stack applies per-token rate limits documented in the developer portal; the OpenAPI spec does not encode these explicitly. Honour 429 responses with backoff, and prefer pulling `/monitors/{monitor_id}/availability` over polling `/monitors/{monitor_id}/response-times` for SLO summaries.

### Can I retrieve response time history for a monitor?

Yes. GET `/monitors/{monitor_id}/response-times` returns response time samples for a monitor over a configurable window, suitable for charting or anomaly detection. Pair with GET `/monitors/{monitor_id}/availability` when reporting SLO compliance.

### Can I limit what my agent is allowed to do with the Better Stack Uptime API?

Yes. Because you run Jentic One yourself, your own rules decide which Better Stack operations and credentials the agent may use. Better Stack puts the monitor id in the URL path (`/monitors/{monitor_id}/...`), so a rule can pin the agent to one monitor and let it read only that monitor's availability and response times. You pick the operations it may call, so incident-resolving via POST `/incidents/{incident_id}/resolve` or status-page edits via PATCH `/status-pages/{status_page_id}` stay off limits unless you add them.