API Documentation

All requests and responses use JSON. Include Content-Type: application/json on all POST and PUT requests.

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.

Authentication

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..."

Errors

All errors return 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
}

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": "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 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..."

Grafana Integration

Use Grafana's Webhook contact point to send pages directly from alert rules.

1. 1In Grafana, go to Alerting → Contact points → Add contact point
2. 2Choose type Webhook
3. 3Set the URL to https://pingparrot.app/api/external/pages
4. 4Add a custom header: X-API-Key: pp_live_your_key_here
5. 5Set HTTP method to POST

For a direct shell script approach, use Grafana's notification templates with a cURL command in a script contact point, or simply call PingParrot from your alerting rules via a webhook proxy.

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\"
  }"