REST API

Programmatic access to incidents, schedules, services, teams, and more.

Base URL

https://api.notifyhero.com/v1

Authentication

All requests require a Bearer token:

curl https://api.notifyhero.com/v1/incidents \
  -H "Authorization: Bearer nh_live_abc123"

Generate API keys at Settings → API Keys. Keys are prefixed:

• nh_live_ — production keys
• nh_test_ — test keys (sandbox environment)

Rate Limits

| Plan | Requests/minute | |------|----------------| | Free | 60 | | Team | 300 | | Business | 1,000 | | Enterprise | 5,000 |

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1709312400

When rate limited, you'll receive 429 Too Many Requests.

Incidents

List Incidents

curl https://api.notifyhero.com/v1/incidents \
  -H "Authorization: Bearer nh_live_abc123" \
  -G -d "status=triggered" -d "limit=10"

Parameters: status (triggered, acknowledged, resolved), service_id, priority, since, until, limit, offset

Get Incident

curl https://api.notifyhero.com/v1/incidents/INC-1042 \
  -H "Authorization: Bearer nh_live_abc123"

Create Incident

curl -X POST https://api.notifyhero.com/v1/incidents \
  -H "Authorization: Bearer nh_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Manual incident — customer reports checkout failures",
    "service_id": "srv_abc123",
    "priority": "P1",
    "severity": "critical",
    "description": "Multiple customer reports of checkout timeouts"
  }'

Acknowledge

curl -X PUT https://api.notifyhero.com/v1/incidents/INC-1042/acknowledge \
  -H "Authorization: Bearer nh_live_abc123"

Resolve

curl -X PUT https://api.notifyhero.com/v1/incidents/INC-1042/resolve \
  -H "Authorization: Bearer nh_live_abc123" \
  -d '{"resolution_note": "Rolled back deploy v2.4.1"}'

Events (Ingest)

Send events through the Events API (same as webhook integrations):

curl -X POST https://events.notifyhero.com/v1/ingest/{integration_key} \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "trigger",
    "severity": "critical",
    "title": "Database connection pool exhausted",
    "source": "db-primary-01",
    "dedup_key": "db-pool-primary-01"
  }'

The Events API has separate, higher rate limits (10,000 events/minute on all plans).

Schedules

List Schedules

curl https://api.notifyhero.com/v1/schedules \
  -H "Authorization: Bearer nh_live_abc123"

Who's On-Call Now

curl https://api.notifyhero.com/v1/schedules/sched_abc123/on-call \
  -H "Authorization: Bearer nh_live_abc123"

Response:

{
  "user": {
    "id": "usr_xyz789",
    "name": "Alice Chen",
    "email": "alice@your-company.com"
  },
  "schedule": "Backend Primary",
  "shift_start": "2026-03-01T09:00:00Z",
  "shift_end": "2026-03-08T09:00:00Z"
}

Services

List Services

curl https://api.notifyhero.com/v1/services \
  -H "Authorization: Bearer nh_live_abc123"

Create Service

curl -X POST https://api.notifyhero.com/v1/services \
  -H "Authorization: Bearer nh_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "checkout-service",
    "description": "Handles payment processing",
    "escalation_policy_id": "ep_abc123"
  }'

Teams

# List teams
curl https://api.notifyhero.com/v1/teams \
  -H "Authorization: Bearer nh_live_abc123"

# Get team members
curl https://api.notifyhero.com/v1/teams/team_abc123/members \
  -H "Authorization: Bearer nh_live_abc123"

Pagination

List endpoints return paginated results:

{
  "data": [...],
  "pagination": {
    "total": 142,
    "limit": 25,
    "offset": 0,
    "has_more": true
  }
}

Use limit and offset query parameters to paginate.

Errors

Standard HTTP status codes with descriptive error bodies:

{
  "error": {
    "code": "not_found",
    "message": "Incident INC-9999 not found",
    "status": 404
  }
}

| Code | Meaning | |------|---------| | 400 | Bad request — check your parameters | | 401 | Unauthorized — invalid or missing API key | | 403 | Forbidden — insufficient permissions | | 404 | Not found | | 429 | Rate limited | | 500 | Server error — retry with backoff |

SDKs

Official SDKs:

# Node.js
npm install @notifyhero/node

# Python
pip install notifyhero

# Go
go get github.com/notifyhero/notifyhero-go

# Ruby
gem install notifyhero

// Node.js example
import { NotifyHero } from '@notifyhero/node';

const nh = new NotifyHero({ apiKey: 'nh_live_abc123' });

const incidents = await nh.incidents.list({ status: 'triggered' });
await nh.incidents.acknowledge('INC-1042');

Webhooks (Outbound)

Subscribe to events from NotifyHero:

curl -X POST https://api.notifyhero.com/v1/webhooks \
  -H "Authorization: Bearer nh_live_abc123" \
  -d '{
    "url": "https://your-company.com/webhooks/notifyhero",
    "events": ["incident.triggered", "incident.resolved"],
    "secret": "your-webhook-secret"
  }'

All outbound webhooks include an X-NotifyHero-Signature header for verification.