canonical: https://jentic.com/apis/kuvasz-uptime.dev/kuvasz-uptime

# Kuvasz Uptime

Jentic publishes the only available OpenAPI specification for Kuvasz Uptime, keeping it validated and agent-ready. Kuvasz is an open-source, self-hostable uptime monitoring and status page service. The v2 API covers HTTP and push monitor lifecycle, SSL events, uptime events, integrations, status pages, and Prometheus metrics, and supports both API key and bearer token authentication. Monitors and status pages can also be exported to YAML for GitOps-style management.

## For AI agents

Manage Kuvasz uptime monitors and status pages: create HTTP and push monitors, fetch SSL and uptime events, configure integrations, and run health checks.

## Scope

Does not handle log aggregation, APM tracing, or on-call paging - use for uptime monitoring, heartbeats, and status pages only.

## Capabilities

- Create HTTP monitors via POST `/api/v2/http-monitors` with target URL, method, and check interval
- Send heartbeats from cron jobs and workers through GET or POST `/api/v2/push-monitors/heartbeats/{clientSecret}`
- Inspect SSL certificate events for a monitor via GET `/api/v2/http-monitors/{monitorId}/ssl-events`
- Pull uptime events for incident reconstruction via `/api/v2/http-monitors/{monitorId}/uptime-events`
- Test notification integrations like Slack, email, and webhooks via POST `/api/v2/integrations/{integrationId}/test`
- Publish status pages and export monitors and status pages to YAML for GitOps via `/export/yaml` endpoints
- Expose Prometheus metrics via GET `/api/v2/prometheus` for ingestion into existing observability stacks

## Use cases

### HTTP Endpoint Monitoring

Monitor public APIs and websites by creating HTTP monitors that probe a URL on a fixed interval. POST `/api/v2/http-monitors` creates the monitor, GET `/api/v2/http-monitors/{monitorId}/uptime-events` lists each up/down transition for incident reconstruction, and GET `/api/v2/http-monitors/{monitorId}/ssl-events` tracks certificate validity.

Example prompt: POST `/api/v2/http-monitors` with the target URL, then poll GET `/api/v2/http-monitors/{monitorId}/uptime-events` to surface transitions in the agent.

### Cron Job Heartbeat Monitoring

Detect failed or skipped scheduled jobs by sending heartbeats from each run. POST `/api/v2/push-monitors` creates the monitor, the job sends a heartbeat to `/api/v2/push-monitors/heartbeats/{clientSecret}` on success and to the /failure variant on error. Kuvasz fires alerts via the configured integrations when heartbeats are missed.

Example prompt: POST `/api/v2/push-monitors` to create the heartbeat monitor, then call `/heartbeats/{clientSecret}` on every successful job run and `/heartbeats/{clientSecret}/failure` on failure.

### GitOps Monitor Management

Manage monitors and status pages as code. GET `/api/v2/monitors/export/yaml` and GET `/api/v2/status-pages/export/yaml` return YAML descriptions that can be committed to Git, reviewed in PRs, and reapplied. This makes monitor configuration auditable and reproducible across environments.

Example prompt: GET `/api/v2/monitors/export/yaml` on a schedule and commit the result to a config repo when the diff is non-empty.

### AI Agent SRE Assistant

An assistant in an SRE chat creates monitors on demand, tests notification integrations, and reports incident status without leaving the chat. Through Jentic, the assistant calls Kuvasz by intent with the API key kept in the vault.

Example prompt: On 'add a monitor for the new payments service', search Jentic for 'create Kuvasz HTTP monitor' and POST `/api/v2/http-monitors` with the URL and interval.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v2/http-monitors` | Create an HTTP monitor |
| POST | `/api/v2/push-monitors` | Create a push (heartbeat) monitor |
| POST | `/api/v2/push-monitors/heartbeats/{clientSecret}` | Send a heartbeat for a push monitor |
| GET | `/api/v2/incidents` | List incidents |
| POST | `/api/v2/integrations/{integrationId}/test` | Send a test notification |
| GET | `/api/v2/monitors/export/yaml` | Export monitors as YAML |
| POST | `/api/v2/status-pages` | Create a status page |

## Key resources

- **HTTP Monitors** — Active probes against URLs with interval, method, and SSL tracking.
- **Push Monitors** — Heartbeat-based monitors for cron jobs and background workers.
- **Incidents** — Aggregated incident records across all monitors.
- **Integrations** — Notification channels for alerts, with a test endpoint.
- **Status Pages** — Public status pages assembled from monitor groups.
- **Settings** — Application-wide configuration.

## Why Jentic

- **Setup:** Wiring Kuvasz Uptime by hand means choosing between its X-API-KEY and bearer auth, passing the right header on every call to your own Kuvasz host, and building the heartbeat and monitor request bodies yourself. Through Jentic you install once, import Kuvasz Uptime from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Kuvasz's monitor and status-page operations take their targets in the request body rather than the URL path, so scope the agent to the operations it needs, such as reading incidents and sending heartbeats. You choose that set, so creating HTTP monitors or status pages is not included unless you add it.
- **Credential handling:** Your Kuvasz API key or bearer token is stored once, encrypted, by your own Jentic One instance, which injects the right header at execution time. The credential never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an HTTP monitor' or 'send a heartbeat', and Jentic returns the matching Kuvasz operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **UptimeRobot API** — Hosted uptime monitoring with a free tier, similar feature scope to Kuvasz.
- **Better Stack API** — Commercial monitoring and incident platform with status pages and on-call.
- **Pingdom API** — Long-running synthetic monitoring service from SolarWinds.
- **Statuspage API** — Atlassian status page service used downstream of monitor data.

## FAQ

### Why is there no official OpenAPI spec for Kuvasz Uptime?

Kuvasz does not publish an OpenAPI specification on a stable URL. Jentic generates and maintains this spec so that AI agents and developers can call Kuvasz Uptime 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 Kuvasz Uptime API use?

Kuvasz supports two schemes: an API key in the X-API-KEY header and HTTP bearer authentication. Through Jentic, both credential types are stored encrypted in your Jentic One instance and the right scheme is selected per request.

### Can I send a heartbeat from a cron job with the Kuvasz Uptime API?

Yes. After creating a push monitor on POST `/api/v2/push-monitors`, send a GET or POST to `/api/v2/push-monitors/heartbeats/{clientSecret}` on success and to `/api/v2/push-monitors/heartbeats/{clientSecret}/failure` on error. Kuvasz alerts through configured integrations when heartbeats are missed.

### How do I create an HTTP monitor through Jentic?

Search Jentic for 'create Kuvasz HTTP monitor'. Jentic returns POST `/api/v2/http-monitors` with its schema. Provide the URL and interval and Jentic executes the call using your stored credentials.

### Is Kuvasz Uptime free to use?

Yes. Kuvasz is open-source and self-hostable. There are no licence fees; you bring your own host and database. The same v2 API runs on every Kuvasz instance.

### Can I export Kuvasz monitors as YAML for GitOps?

Yes. GET `/api/v2/monitors/export/yaml` and GET `/api/v2/status-pages/export/yaml` return YAML representations suitable for committing to a Git repository, reviewing in pull requests, and reapplying.

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

Yes. Because you run Jentic One yourself, your own rules decide which Kuvasz operations and stored credentials the agent can use, so you can allow read-only calls like listing incidents on GET `/api/v2/incidents` and sending heartbeats to `/api/v2/push-monitors/heartbeats/{clientSecret}` while withholding write operations. Kuvasz takes its monitor and status-page targets in the request body rather than the URL path, so you scope by operation: creating HTTP monitors on POST `/api/v2/http-monitors` or status pages on POST `/api/v2/status-pages` is excluded unless you add it. The agent can only call the endpoints you grant, and the API key or bearer token stays under your control.