# Uptime API

The Uptime API lets scripts and CI jobs do what the Uptime console does: create and change monitors, pause them around a deploy, read their check history and uptime, silence alerts for planned work, and decide where alerts go. Every endpoint, with its parameters, schemas, errors and an example request, is in the [Uptime API reference](https://docs-dev.evohub.io/uptime.md). This page shows the common tasks and the rules that apply to all of them.

Paths below are relative to `https://evohub.io`. Requests need an API key, sent as described in [API overview](https://docs-dev.evohub.io/api-overview.md#authentication).

## Scopes

Each endpoint needs one scope. Give a key only the ones its job needs.

| To | Scope |
| --- | --- |
| List and read monitors, checks, uptime, analytics and the weekly summary settings | `uptime:monitor:read` |
| Create, change, pause, resume and delete monitors | `uptime:monitor:write` |
| Read a monitor's outages | `uptime:incident:read` |
| Read silences | `uptime:silence:read` |
| Silence the organization or a monitor, and lift it | `uptime:silence:write` |
| Read notification channels and which monitors use them | `uptime:channel:read` |
| Create and delete channels, link and unlink them | `uptime:channel:write` |
| Read the Uptime audit log | `uptime:audit:read` |

A key without the scope gets **403**, never 401. See [Errors](https://docs-dev.evohub.io/errors.md#401-versus-403).

## Create a monitor

```bash
curl https://evohub.io/api/v1/monitors \
  -H "Authorization: Bearer $EVOHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout API",
    "type": "http",
    "url": "https://api.acme.example/health",
    "interval_seconds": 60,
    "timeout_seconds": 10,
    "is_active": true,
    "sla_target": 99.9
  }'
```

The answer is the monitor, with its `id`. `name`, `type`, `interval_seconds` and `timeout_seconds` are required. A monitor created without `"is_active": true` starts paused.

The `type` decides what `url` must be: an `http(s)` URL for `http` and `keyword`, `host:port` for `tcp`, a host for `icmp`, and nothing for `heartbeat`. Assertions, slow-response thresholds and SLA targets are described in [Uptime monitoring](https://docs-dev.evohub.io/uptime-overview.md).

## Pause and resume

There is no separate pause endpoint: change `is_active`.

```bash
# Pause before a deploy
curl -X PATCH https://evohub.io/api/v1/monitors/$MONITOR_ID \
  -H "Authorization: Bearer $EVOHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

# Resume afterwards
curl -X PATCH https://evohub.io/api/v1/monitors/$MONITOR_ID \
  -H "Authorization: Bearer $EVOHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": true}'
```

A paused monitor is not checked and raises no alerts. `PATCH` changes only the fields you send, so the same call can change anything else about a monitor.

## Silence a monitor for planned work

If you want the monitor to keep being checked but not page anyone, give it a silence window instead of pausing it. It needs `uptime:silence:write`.

```bash
curl -X PUT https://evohub.io/api/v1/monitors/$MONITOR_ID/silence \
  -H "Authorization: Bearer $EVOHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"starts_at": "2026-10-12T22:00:00Z", "ends_at": "2026-10-13T00:00:00Z"}'
```

A monitor has one window; setting a new one replaces it, and `DELETE` on the same path removes it. To mute every monitor of the organization for a while, `PUT /api/v1/silence` with `{"minutes": 60}`. See [Alerts and silence windows](https://docs-dev.evohub.io/uptime-alerts-and-silence-windows.md).

## Read uptime and SLA

- `GET /api/v1/monitors/{id}` returns the monitor with `uptime_percent` for `24h`, `7d`, `30d` and `90d`, and `sla_breached_30d` when it has an SLA target.
- `GET /api/v1/monitors/{id}/uptime/daily?days=90` returns one entry per UTC day for an uptime calendar.
- `GET /api/v1/uptime/analytics?from=2026-09-01&to=2026-09-30` returns uptime, latency, outages and SLA results for every monitor you can see, with a time series and a row per monitor and team.

## Heartbeat monitors

A heartbeat monitor's job calls its ping URL, `https://evohub.io/ping/{ping_token}`. The `ping_token` is in the monitor returned when you create it. The ping URL does not take an API key — the token is the credential — and it is not rate limited. See [Heartbeat monitors](https://docs-dev.evohub.io/heartbeat-monitors.md).

## Notification channels

Create a channel with `POST /api/v1/notification-channels`, then link it to a monitor with `POST /api/v1/monitors/{id}/channels/{channelId}`. For a Slack or chat app channel, list the choices with `GET /api/v1/notification-channels/chat-apps` and create a `chat` channel with the `id` you pick.

A webhook channel's URL and secret are write-only. Reads show only the host, a short hint of the path and whether a secret is set:

```json
{
  "id": "nch_6a9d2f4b-8c1e-4b3a-9f7d-5e0c2a8b4d16",
  "name": "Incident bridge",
  "type": "webhook",
  "config": { "url_host": "hooks.acme.example", "url_hint": "…/5b1d", "has_secret": true }
}
```

To change a webhook's URL, create a new channel and delete the old one.

## Things to know

- **Teams.** A key sees the organization-wide monitors, plus a team's monitors when it is an organization key scoped to that team. A monitor it cannot see answers **404** `MONITOR_NOT_FOUND`, the same as one that does not exist.
- **Monitor credentials are write-only.** A monitor's Basic Auth password and header values are never returned. Reads show `has_http_auth_password` and `http_headers` as `[{"name": "Authorization", "has_value": true}]`. On `PATCH`, leave `http_auth_password` out to keep it (send `""` to remove it). Send a header with an empty value to keep its stored value. The list you read can be sent back as it is.
- **Credentials in a monitor URL are masked.** Reads show `https://user:pass@…` as `https://****:****@…` and the value of a `token`, `key`, `secret`, `password`, `sig`, `signature`, `auth`, `api_key` or `access_token` query parameter as `****`. Checks use the URL as you entered it. The masked URL can be sent back on `PATCH`: each `****` keeps the stored value, so you can change the path or another parameter without re-entering the credentials.
- **Empty lists.** The monitor, check, outage and audit log lists answer `{"data": []}` when there is nothing to list.
- **Weekly summary.** A key can read the weekly summary settings and change its owner's own subscription, but turning the summary on or off and sending a preview need an owner or administrator signed in to the console.
- **Errors.** Branch on `error.code`. The codes each endpoint returns are listed in the reference; the general rules are in [Errors](https://docs-dev.evohub.io/errors.md).

## Related

- [Uptime API reference](https://docs-dev.evohub.io/uptime.md)
- [API overview](https://docs-dev.evohub.io/api-overview.md)
- [API keys and scopes](https://docs-dev.evohub.io/api-keys-and-scopes.md)
- [Uptime monitoring](https://docs-dev.evohub.io/uptime-overview.md)