API Documentation

All requests and responses use JSON, per the JSON specification. Include Content-Type: application/json on all POST and PUT requests. Status codes follow the IANA HTTP status code registry — 2xx for success, 4xx for a request you can fix, 5xx for something on our end.

PingParrot offers two authentication methods depending on your use case:

• →API Key — for monitoring tools, scripts, and third-party integrations. Generate a key in your dashboard. Simple header-based auth.
• →Bearer Token — for user-authenticated sessions. Login via the API to get a token. Required for reading pages, managing groups, etc.

How do I authenticate with the API?

Use an API key for integrations, or a bearer token for user-authenticated sessions — both go in a request header, no OAuth flow required.

curl -X POST https://pingparrot.app/api/external/pages \
  -H "X-API-Key: pp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Server down", "message": "web-01 is unreachable", "priority": "critical", "delivery_mode": "broadcast"}'

curl -X POST https://pingparrot.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "device_name": "my-script"
  }'

{
  "token": "1|abc123xyz...",
  "user": {
    "id": 1,
    "name": "Jane Smith",
    "email": "[email protected]",
    "is_admin": true
  }
}

curl https://pingparrot.app/api/auth/me \
  -H "Authorization: Bearer 1|abc123xyz..."

curl -X POST https://pingparrot.app/api/auth/logout \
  -H "Authorization: Bearer 1|abc123xyz..."

What do error responses look like?

Every error returns JSON with an error key. Validation errors return a message and an errors object.

Send a Page

The core endpoint. Use this from your monitoring tools, scripts, or integrations.

Request Body

Response 201 Created

{
  "message": "Page sent successfully",
  "page_id": 42,
  "recipients": 3
}

Response — Suppressed by Maintenance Window

When an active maintenance window covers the target group or organisation, the page is saved with status suppressed and a 201 is returned with suppressed: true. No push notifications are sent.

{
  "message": "Page suppressed by active maintenance window",
  "page_id": 43,
  "suppressed": true,
  "window": "DB Cluster Maintenance"
}

Delivery Modes

{
  "subject": "All hands — production is down",
  "message": "Database cluster unreachable. All services affected.",
  "priority": "critical",
  "delivery_mode": "broadcast",
  "repeat_interval_s": 30
}

{
  "subject": "Disk usage critical on web-01",
  "message": "Disk at 97%. Immediate attention required.",
  "priority": "high",
  "delivery_mode": "group",
  "target_group_id": 2,
  "repeat_interval_s": 60
}

{
  "subject": "Disk usage above 90% on db-prod-01",
  "message": "Disk /dev/sda1 at 92%. Immediate attention required.",
  "priority": "critical",
  "delivery_mode": "oncall",
  "target_schedule_id": 1
}

{
  "subject": "Your deployment failed",
  "message": "Build #1024 failed at test stage. See CI logs.",
  "priority": "normal",
  "delivery_mode": "single",
  "target_user_id": 5
}

Escalation Rules

Automatically escalate to another person or group if the page isn't acknowledged within a set time. Escalation rules are evaluated after initial delivery.

Escalation Object Fields

Example — page primary on-call, escalate to manager after 5 minutes

{
  "subject": "Payment service is down",
  "message": "Stripe webhook endpoint returning 503.",
  "priority": "critical",
  "delivery_mode": "single",
  "target_user_id": 3,
  "repeat_interval_s": 30,
  "escalation": [
    {
      "step": 1,
      "delay_seconds": 300,
      "escalate_to_user_id": 1,
      "repeat_page": true
    }
  ]
}

List Pages

Returns a paginated list of pages. Admins see all pages; regular users see only pages they are a recipient of.

Query Parameters

curl "https://pingparrot.app/api/pages?status=active" \
  -H "Authorization: Bearer 1|abc123xyz..."

Get a Page

Returns full details for a single page including recipients and acknowledgements.

curl https://pingparrot.app/api/pages/42 \
  -H "Authorization: Bearer 1|abc123xyz..."

{
  "id": 42,
  "subject": "Server down",
  "message": "web-01 is unreachable",
  "priority": "critical",
  "status": "active",
  "delivery_mode": "broadcast",
  "repeat_interval_s": 30,
  "created_at": "2026-06-23T14:00:00Z",
  "expires_at": null,
  "recipients": [
    {
      "id": 12,
      "user_id": 3,
      "status": "pending",
      "first_sent_at": "2026-06-23T14:00:01Z",
      "acknowledged_at": null,
      "user": { "id": 3, "name": "Sarah M." }
    }
  ]
}

Acknowledge a Page

Marks the page as acknowledged for the authenticated user. When all recipients have acknowledged, the page status changes to acknowledged and repeating stops.

Request Body (all optional)

curl -X POST https://pingparrot.app/api/pages/42/acknowledge \
  -H "Authorization: Bearer 1|abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{"response_note": "Restarted the service, monitoring now."}'

Cancel a Page

Stops repeating and marks the page as cancelled. Admin only.

curl -X DELETE https://pingparrot.app/api/pages/42 \
  -H "Authorization: Bearer 1|abc123xyz..."

List Schedules

Returns all on-call schedules in your organisation, with whoever's currently covering each one. Use the returned id as target_schedule_id when sending a page with delivery_mode: oncall. Same API key as Send a Page — no dashboard login needed.

curl https://pingparrot.app/api/external/schedules \
  -H "X-Api-Key: pp_live_your_key_here"

[
  {
    "id": 1,
    "name": "Backend On-Call",
    "on_call_user": { "id": 14, "name": "Alex Rivera" },
    "fallback_group": null
  },
  {
    "id": 2,
    "name": "Infra On-Call",
    "on_call_user": null,
    "fallback_group": { "id": 3, "name": "Infra Team" }
  }
]

on_call_user is null when nobody's currently scheduled. In that case a page sent with delivery_mode: oncall goes to fallback_group instead, if the schedule has one set (configurable on the On-Call Schedules page) — otherwise it reaches nobody. Check both fields before relying on delivery.

List Groups (API Key)

Same data as List Groups below, but reachable with an API key — no Bearer Token or dashboard login needed. Use the returned id as target_group_id.

curl https://pingparrot.app/api/external/groups \
  -H "X-Api-Key: pp_live_your_key_here"

[
  { "id": 2, "name": "Backend Team", "member_count": 6 },
  { "id": 3, "name": "Infra Team", "member_count": 4 }
]

List Groups

Returns all active groups in your organisation. Use the returned IDs when sending a page with delivery_mode: group.

curl https://pingparrot.app/api/groups \
  -H "Authorization: Bearer 1|abc123xyz..."

[
  { "id": 1, "name": "All", "description": "All pagers in your organization", "is_active": true },
  { "id": 2, "name": "DevOps", "description": "On-call engineers", "is_active": true }
]

Get a Group

Returns a group with its current members.

curl https://pingparrot.app/api/groups/2 \
  -H "Authorization: Bearer 1|abc123xyz..."

Snooze

Toggle your personal notification snooze on or off. When snoozed, pages dispatched to a group or broadcast will skip you — you will not receive push notifications for those pages. On-call and direct (single-user) pages still reach you even when snoozed.

No request body required. Each call flips the current snooze state.

Response

{
  "is_snoozed": true
}

curl -X POST https://pingparrot.app/api/auth/snooze/toggle \
  -H "Authorization: Bearer 1|abc123xyz..."

Grafana Integration

Use Grafana's Webhook contact point to call the PingParrot API when an alert fires.

1. 1In Grafana, go to Alerting → Contact points → Add contact point
2. 2Choose type Webhook and set the URL to https://pingparrot.app/api/external/pages
3. 3Add header X-Api-Key: YOUR_API_KEY and set method to POST

Prometheus / Alertmanager

Add PingParrot as a webhook receiver in alertmanager.yml and your alerts route directly to your on-call team.

receivers:
  - name: 'pingparrot'
    webhook_configs:
      - url: 'https://pingparrot.app/api/external/pages'
        http_config:
          headers:
            X-Api-Key: 'YOUR_API_KEY'
        send_resolved: false

route:
  receiver: 'pingparrot'

Generic Webhook / Any Tool

Any monitoring tool that can make an HTTP POST request — Nagios, Zabbix, Uptime Robot, custom scripts, CI pipelines — can trigger PingParrot.

curl -X POST https://pingparrot.app/api/external/pages \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Alert: high CPU on web-01",
    "message": "CPU at 95% for 5 minutes.",
    "priority": "critical",
    "target": "oncall",
    "schedule_id": 1
  }'

cURL Examples

curl -X POST https://pingparrot.app/api/external/pages \
  -H "X-API-Key: pp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Production is down",
    "message": "All services returning 503. Immediate action required.",
    "priority": "critical",
    "delivery_mode": "broadcast",
    "repeat_interval_s": 30
  }'

curl -X POST https://pingparrot.app/api/external/pages \
  -H "X-API-Key: pp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "High memory usage on app-server-02",
    "message": "Memory at 95%. OOM kill likely within minutes.",
    "priority": "high",
    "delivery_mode": "group",
    "target_group_id": 2,
    "repeat_interval_s": 60,
    "expires_minutes": 30
  }'

#!/bin/bash
# Usage: ./ping.sh "Subject" "Message body" "critical"

SUBJECT="${1:-Alert}"
MESSAGE="${2:-No details provided}"
PRIORITY="${3:-normal}"

curl -s -X POST https://pingparrot.app/api/external/pages \
  -H "X-API-Key: $PINGPARROT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"subject\": \"$SUBJECT\",
    \"message\": \"$MESSAGE\",
    \"priority\": \"$PRIORITY\",
    \"delivery_mode\": \"broadcast\"
  }"