API Reference

Everything in Zharp is an HTTP API: monitors, incidents, status pages, alerting, on-call, logs, traces and your team. This page covers what every request shares; each area has its own page with every endpoint.

Quick start

1. 1
   Create a key

   In the dashboard, open Integrations & API → Main API keys → Create API key. Pick its scopes and expiry, optionally the addresses it may be used from, and copy it — it's shown once. Keys are on every plan.

2. 2
   Call the API

   Every path is relative to https://api.zharp.io/api/v1, and the key goes in an Authorization header:

   export ZHARP_API_KEY=zh_live_…
   
   curl "https://api.zharp.io/api/v1/monitors?status=DOWN" \
     -H "Authorization: Bearer $ZHARP_API_KEY"

Authentication

Send the key as a bearer token: Authorization: Bearer zh_live_…. The ingestion endpoints that agents and SDKs post data to take it as X-API-KEY instead (see Logs).

• A key belongs to one workspace and only ever acts on it — no X-Workspace-Id needed, and one sent is ignored. Another workspace's ids answer 404; another workspace's /workspaces/:id answers 403.
• A key acts as the person who created it. Their role in the workspace limits what it can do (see Roles), and the key's scope narrows that further. If they leave, their keys stop working.
• Some routes are for people, not keys: signing in, profiles, the list of your workspaces, accepting invitations, personal notification settings, billing, and deleting a workspace. Keys get 401 there.
• On a key's page you can limit it to Allowed IPs, change its expiry, Roll key or Revoke it, and see its last day of requests — or do it all through the API.

Scopes

A key holds one or more scopes. The strongest counts: admin includes write, and write includes read.

Each endpoint shows the scope it needs.

Roles and permissions

Each endpoint also shows the permission it needs from the key's owner, when it needs one. Which role holds which:

resources:manage covers incidents, maintenance, status pages, alert connections and monitor groups. A permission the key's owner lacks answers 403, whatever the key's scope.

Requests and responses

• Send JSON with Content-Type: application/json; uploads are multipart/form-data. Bodies can be up to 10 MB.
• Times are ISO 8601 in UTC, 2026-10-26T09:14:32.041Z; send them the same way. A few chart fields are epoch seconds and say so.
• Uptime is always a percentage from 0 to 100, such as 99.95; -1 in a chart means no checks in that hour or day.
• :id in a path is a number. PUT changes only the fields you send, except where a page says it replaces the whole thing.
• Credentials stored in Zharp — monitor passwords, auth headers, connection secrets — come back as ••••••••. Send that value back unchanged and the stored one is kept.

A success wraps the result in data:

{
  "message": "Monitors retrieved successfully",
  "data": [ … ]
}

Lists that page add meta; send page and limit to move through them. Others take limit and offset, as each page says.

{
  "message": "Incidents retrieved successfully",
  "data": [ … ],
  "meta": { "total": 60, "page": 1, "limit": 50, "totalPages": 2 }
}

Errors

An error has a message for people and an errorCode for code:

{
  "message": "This API key lacks the \"admin\" scope required for POST /monitors",
  "errorCode": "accessDenied"
}

Rate limits

Each key can make 1,000 requests per minute, counted in calendar minutes (UTC) across all our servers. Past that, requests get 429 until the minute turns. Sending data — logs, traces, heartbeats, pushes — doesn't count against it; logs have the monthly allowance instead.

Endpoints that need no key

Examples

# Is anything down?
curl "https://api.zharp.io/api/v1/monitors?status=DOWN" -H "Authorization: Bearer $ZHARP_API_KEY"

# Acknowledge an incident, then resolve it (write key)
curl -X POST "https://api.zharp.io/api/v1/incidents/481/acknowledge" -H "Authorization: Bearer $ZHARP_API_KEY"
curl -X POST "https://api.zharp.io/api/v1/incidents/481/resolve" -H "Authorization: Bearer $ZHARP_API_KEY"

# Tell visitors on your status page (write key)
curl -X POST "https://api.zharp.io/api/v1/status-pages/12/announcements" \
  -H "Authorization: Bearer $ZHARP_API_KEY" -H "Content-Type: application/json" \
  -d '{ "title": "API latency", "content": "We are investigating.", "status": "INVESTIGATING", "affectedMonitorIds": [57] }'

# Create a monitor (admin key)
curl -X POST "https://api.zharp.io/api/v1/monitors" \
  -H "Authorization: Bearer $ZHARP_API_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "HTTP", "name": "Homepage", "url": "https://acme.io", "interval": 300 }'

Rather not poll?

A webhook pushes every monitor and incident event to you as it happens. For logs and traces, the SDKs handle batching and retries. And the MCP server lets an AI assistant read your monitors and incidents.