Management API reference

Authentication and tokens

The base URL is https://znowpulse.com/api/v1. Requests are scoped to the organization associated with the token. An owner or admin creates tokens in Settings → API access, choosing only the required scopes and completing any password confirmation. Copy the raw token when it is revealed; it is shown once. Store it in your automation's secret store and revoke it when no longer needed.

Send Authorization: Bearer YOUR_TOKEN on every request and Content-Type: application/json on JSON writes. The token prefix is znp_live_. A token cannot bypass its creator's current role or the organization's plan. Do not put tokens in browser code, URLs, or a public repository.

First request

The examples assume your shell environment already contains ZNOWPULSE_API_TOKEN, supplied securely by your secret store. Replace sample targets and IDs with your own.

curl --fail-with-body 'https://znowpulse.com/api/v1/monitors?limit=50' \
  -H "Authorization: Bearer $ZNOWPULSE_API_TOKEN"

Successful REST responses use a data envelope. The monitor list also returns meta.next_cursor. Pass that cursor back as the cursor query parameter, URL-encoded, to read the next page. The default monitor page size is 50; the maximum is 100.

{
  "data": [],
  "meta": { "next_cursor": null }
}

This is an illustrative empty response, not live workspace data. Resource routes use public IDs returned by the API. On-call member fields are an exception: member_user_ids and user_id take numeric organization member IDs.

Create a monitor

This example explicitly chooses a five-minute interval so it can be used on Free. Change https://example.com/health to a public health endpoint you control.

curl --fail-with-body 'https://znowpulse.com/api/v1/monitors' \
  -H "Authorization: Bearer $ZNOWPULSE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: production-health-monitor-v1' \
  --data '{"name":"Production health","url":"https://example.com/health","type":"http","interval_seconds":300,"public_page_visible":false}'

Creation returns HTTP 201 and { "data": { ...monitor } }. Save the returned id for later requests. A created monitor may be pending until it has a completed check.

Field	Type and behavior
name	Required string, 1–160 characters.
url	Required target string, up to 2,048 characters. Subject to target validation.
type	http, minecraft, tcp, icmp, or dns; defaults to http.
interval_seconds	Integer, 10–86,400; defaults to 60. Free requires at least 300, so set it explicitly on Free.
group_name	Optional string up to 120 characters, or null.
tags	Optional array of up to 30 strings, each 1–64 characters.
http	Optional HTTP configuration object described below.
tcp_port	Optional integer port, 1–65,535.
dns_record_type	A, AAAA, CNAME, MX, TXT, or SRV.
dns_expected_value	Optional expected DNS value, up to 2,048 characters.
regions	Optional array of advertised region codes; multiple regions require Pro.
confirmation_policy	all_selected (default), majority, or any_region.
public_page_visible	Boolean, default false. Opts the monitor into enabled public views.

The http object accepts method (default GET), headers (string-to-string object), keyword, keyword_match (presence or absence), basic_auth (username and password), and ssl_monitor_enabled (boolean, default false). Header names and values cannot contain newlines.

PATCH accepts a subset of monitor creation fields, plus is_paused. Use the resource route with the returned monitor ID. DELETE permanently removes that monitor.

Supported REST endpoints

All paths below are relative to /api/v1. Writes need their listed scope and an appropriate current role, generally editor or higher; token management itself is an owner/admin action.

Method	Path	Scope	Purpose
GET	/organization	organization:read	Organization public ID and name.
GET	/monitors	monitors:read	Paginated monitor list.
POST	/monitors	monitors:write	Create a monitor.
GET	/monitors/{id}	monitors:read	Inspect a monitor.
PATCH	/monitors/{id}	monitors:write	Edit or pause a monitor.
DELETE	/monitors/{id}	monitors:write	Delete a monitor.
GET	/monitors/{id}/checks	checks:read	Recent check results; optional limit.
GET	/regions	regions:read	Discover advertised monitoring regions.
GET	/incidents	incidents:read	List organization incidents.
PATCH	/incidents/{id}	incidents:write	Update an existing incident.
GET	/maintenance	maintenance:read	List maintenance windows.
POST	/maintenance	maintenance:write	Create a one-time window.
GET, POST	/nexus-points	nexus_points:read / nexus_points:write	List or create Nexus Points.
GET, PATCH, DELETE	/nexus-points/{id}	nexus_points:read / nexus_points:write	Inspect, edit, or delete a Nexus Point.
GET, POST	/on-call/schedules	on_call:read / on_call:write	List or create schedules; Pro.
GET, POST	/on-call/policies	on_call:read / on_call:write	List or create policies; Pro.
GET	/on-call/alerts	on_call:read	List alerts; Pro.
PUT	/monitors/{id}/escalation-policy	on_call:write	Attach or detach a policy; Pro.
POST	/on-call/alerts/{id}/acknowledge	on_call:write	Acknowledge an open alert; Pro.
POST	/integrations/self/revoke	Authenticated token	Revoke the calling token.

The current REST API does not implement POST /incidents, incident-detail GET, or general edit/delete routes for maintenance windows. Use the app for operations not listed here. The REST incident list currently returns the organization's list without query filtering; MCP's list_incidents exposes filters separately.

Incident updates

PATCH /incidents/{id} accepts optional title, severity (critical, major, minor, info), status (ongoing, investigating, resolved), resolved_reason, and message. A message adds a timeline update; resolving sets the incident's end time. The success data contains id and updated: true.

{
  "status": "resolved",
  "resolved_reason": "Recovered after configuration rollback.",
  "message": "Fresh health checks confirm recovery."
}

Maintenance creation

POST /maintenance requires name, start_time, and end_time. Use ISO UTC timestamps such as 2026-10-01T01:00:00Z; the end must follow the start. Optional fields are description and monitor_ids, an array of up to 200 public monitor IDs. Supply the intended monitor IDs explicitly. Every ID must belong to the token's organization. This route does not expose recurrence fields.

Nexus Point writes

POST /nexus-points takes name, optional description, muted, alert_on_degraded, and a nonempty conditions array. Each condition contains monitor_id, type (STATUS_UP, STATUS_NOT_DOWN, LATENCY_LT, or LATENCY_GT), optional numeric value, and critical (default true). Latency conditions require a non-negative value. Referenced monitors must belong to the same organization. Free's one-Nexus-Point quota still applies.

PATCH accepts changed fields. If supplying conditions, send the intended complete condition set rather than an individual condition patch.

On-call writes

Schedule creation accepts name, timezone, handoff_time, rotation_days, and member_user_ids. Policy creation accepts name, repeat_count, and ordered steps containing delay_minutes, a schedule_id or user_id, channel, and target. Policy channels are email or webhook. Referenced users and schedules must belong to the organization.

Assign a policy with PUT /monitors/{id}/escalation-policy and { "policy_id": "RETURNED_POLICY_ID" }. Send { "policy_id": null } to detach it. Acknowledge an open alert using POST /on-call/alerts/{id}/acknowledge; no JSON body is required.

Retries and errors

Monitor creation supports Idempotency-Key. Reuse the same key and identical request for a retry within 24 hours; a replay returns Idempotent-Replayed: true. Reusing the key for a different request returns 409. Do not assume other creation endpoints have idempotency support. After an ambiguous timeout on those endpoints, read the current state before retrying.

API handler responses include X-Request-Id. Error responses from these handlers use this shape:

{
  "error": {
    "code": "missing_scope",
    "message": "This operation requires the monitors:write scope.",
    "request_id": "req_example"
  }
}

Missing or invalid credentials produce 401. Scope, role, and plan errors explain missing access; not-found errors use 404. Rate limiting can return 429 before the handler, with a different response shape. Treat all non-success responses as failures, retain the request ID when supplied, and use bounded retries only where safe. Do not rely on every invalid body producing the same validation status.