API Documentation

Complete API reference for PingBuoy monitoring service

Getting Started

The PingBuoy API allows you to programmatically manage your website monitoring, alerts, and integrations. Our REST API uses standard HTTP methods and returns JSON responses.

Base URL

https://pingbuoy.com/api

Quick Example

Get your monitored sites

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://pingbuoy.com/api/sites

Field Naming Conventions

The API uses different naming conventions for different resource types:

snake_caseUsed for Sites/Monitoring endpoints (matches database schema): last_checked, created_at, user_id

camelCaseUsed for Integrations/API Keys endpoints (JavaScript-friendly): lastUsed, createdAt, totalRequests

This intentional design provides optimal ergonomics for each API context while maintaining consistency within each resource type.

Authentication

PingBuoy uses API keys for authentication. Include your API key in the Authorization header of all requests.

Security Notice

Keep your API keys secure and never expose them in client-side code. Rotate keys regularly for enhanced security.

Creating API Keys

Generate API keys in your dashboard integrations page.

Using API Keys

Authentication Header

Authorization: Bearer pb_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345

Rate Limits

API requests are rate limited per operation type to ensure system stability and fair usage.

Operation	Rate Limit
Site creation/deletion	10 per hour
Integration operations	20 per hour
Manual monitoring triggers	10 per hour
Data exports	3 per hour

Site creation/deletion

Rate Limit10 per hour

Integration operations

Rate Limit20 per hour

Monitoring checks

Rate Limit100 per hour

Rate Limit Headers

All API responses include rate limit information in headers:

Response Headers

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 2025-01-15T11:00:00.000Z

Rate Limit Exceeded

When rate limited, the API returns HTTP 429 with a Retry-After header indicating seconds until reset.

Websites

GET

/api/sites

Retrieve all monitored sites

Parameters

Name	Type	Required	Description
status	string	Optional	Filter by status (up, down, unknown)

status

Typestring

RequiredNo

DescriptionFilter by status (up, down, unknown)

Response

[
  {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com",
    "type": "website",
    "status": "up",
    "last_checked": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "user_id": "uuid",
    "is_active": true
  }
]

Example

cURL Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/sites"

POST

/api/sites

Add a new site to monitor

Parameters

Name	Type	Required	Description
name	string	Required	Site display name (max 100 chars)
url	string	Required	Site URL to monitor (must be valid URL)
type	string	Optional	Site type: "website" or "api_endpoint" (default: "website")

name

Typestring

RequiredYes

DescriptionSite display name (max 100 chars)

url

Typestring

RequiredYes

DescriptionSite URL to monitor (must be valid URL)

type

Typestring

RequiredNo

DescriptionSite type: "website" or "api_endpoint" (default: "website")

Response

{
  "id": "uuid",
  "name": "My Website",
  "url": "https://example.com",
  "type": "website",
  "status": "unknown",
  "user_id": "uuid",
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "last_checked": null
}

Example

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Website", "url": "https://example.com", "type": "website"}' \
  https://pingbuoy.com/api/sites

DELETE

/api/sites?id={id}

Remove a site from monitoring

Parameters

Name	Type	Required	Description
id	string	Required	Site UUID (query parameter)

Typestring

RequiredYes

DescriptionSite UUID (query parameter)

Response

{
  "success": true
}

Example

cURL Example

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/sites?id=SITE_UUID"

Monitoring Data

POST

/api/monitoring/trigger

Manually trigger a monitoring check for a site

Parameters

Name	Type	Required	Description
action	string	Required	Check type: "uptime", "pagespeed", or "deadlinks"
siteId	string	Required	Site UUID to check

action

Typestring

RequiredYes

DescriptionCheck type: "uptime", "pagespeed", or "deadlinks"

siteId

Typestring

RequiredYes

DescriptionSite UUID to check

Response

{
  "success": true,
  "site": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "result": {
    "type": "uptime",
    "status": "up",
    "responseTime": 234,
    "statusCode": 200,
    "sslValid": true
  }
}

Example

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "uptime", "siteId": "SITE_UUID"}' \
  https://pingbuoy.com/api/monitoring/trigger

GET

/api/integrations

Get all your integrations (Slack, Discord, Webhooks)

Response

[
  {
    "id": "uuid",
    "name": "Slack Alerts",
    "type": "slack",
    "status": "active",
    "config": {
      "events": ["downtime", "recovery"]
    },
    "lastTest": "2025-01-15T10:30:00Z",
    "lastTestStatus": "success",
    "totalNotifications": 42
  }
]

Example

cURL Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/integrations"

POST

/api/integrations

Create a new integration

Parameters

Name	Type	Required	Description
name	string	Required	Integration name (max 100 chars)
integration_type	string	Required	Type: slack, discord, or webhook
webhook_url	string	Required	Webhook URL (must be valid URL format)
events	array	Optional	Events to monitor (downtime, recovery, page_speed, ssl_expiration, dead_links (default: all events))

name

Typestring

RequiredYes

DescriptionIntegration name (max 100 chars)

integration_type

Typestring

RequiredYes

DescriptionType: slack, discord, or webhook

webhook_url

Typestring

RequiredYes

DescriptionWebhook URL (must be valid URL format)

events

Typearray

RequiredNo

DescriptionEvents to monitor (downtime, recovery, page_speed, ssl_expiration, dead_links (default: all events))

Response

{
  "success": true,
  "integration": {
    "id": "uuid",
    "name": "My Slack Integration",
    "type": "slack",
    "status": "active",
    "config": {
      "events": ["downtime", "recovery", "ssl_expiry"]
    }
  }
}

Example

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Alerts",
    "integration_type": "slack",
    "webhook_url": "https://hooks.slack.com/services/...",
    "events": ["downtime", "recovery"]
  }' \
  https://pingbuoy.com/api/integrations

DELETE

/api/integrations?id={id}

Delete an integration

Parameters

Name	Type	Required	Description
id	string	Required	Integration UUID (query parameter)

Typestring

RequiredYes

DescriptionIntegration UUID (query parameter)

Response

{
  "success": true
}

Example

cURL Example

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/integrations?id=INTEGRATION_UUID"

API Keys

GET

/api/keys

Get all your API keys

Response

[
  {
    "id": "uuid",
    "name": "Production API Key",
    "prefix": "pb_12345",
    "permissions": ["read", "write"],
    "status": "active",
    "totalRequests": 1234,
    "lastUsed": "2025-01-15T10:30:00Z",
    "createdAt": "2025-01-01T00:00:00Z"
  }
]

Example

cURL Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/keys"

POST

/api/keys

Generate a new API key

Parameters

Name	Type	Required	Description
name	string	Required	API key name (max 100 chars)
permissions	array	Required	Array of permissions (at least 1 required): ["read"], ["read", "write"], or ["read", "write", "admin"]

name

Typestring

RequiredYes

DescriptionAPI key name (max 100 chars)

permissions

Typearray

RequiredYes

DescriptionArray of permissions (at least 1 required): ["read"], ["read", "write"], or ["read", "write", "admin"]

Response

{
  "success": true,
  "key": "pb_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345",
  "apiKey": {
    "id": "uuid",
    "name": "My API Key",
    "prefix": "pb_12345",
    "permissions": ["read", "write"],
    "status": "active"
  }
}

Example

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "permissions": ["read", "write"]
  }' \
  https://pingbuoy.com/api/keys

DELETE

/api/keys?id={id}

Revoke an API key

Parameters

Name	Type	Required	Description
id	string	Required	API key UUID (query parameter)

Typestring

RequiredYes

DescriptionAPI key UUID (query parameter)

Response

{
  "success": true
}

Example

cURL Example

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/keys?id=KEY_UUID"

Webhooks

Webhooks allow you to receive real-time notifications when incidents occur. PingBuoy will send HTTP POST requests to your configured endpoints.

Webhook Payload

Downtime Alert Payload

{
  "event": "website.down",
  "timestamp": "2025-01-12T10:30:00Z",
  "website": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "incident": {
    "id": "uuid",
    "status_code": 503,
    "response_time": null,
    "error_message": "Service Unavailable"
  },
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

All Webhook Events

PingBuoy sends webhooks for the following event types:

Recovery Alert

Recovery Alert Payload

{
  "event": "website.recovery",
  "timestamp": "2025-01-12T10:35:00Z",
  "website": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "incident": {
    "id": "uuid",
    "downtime_duration_seconds": 300,
    "status_code": 200,
    "response_time": 234
  },
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

SSL Expiration Warning

SSL Expiration Warning Payload

{
  "event": "ssl_expiration",
  "timestamp": "2025-01-12T10:30:00Z",
  "website": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "ssl": {
    "expires_at": "2025-01-20T00:00:00Z",
    "days_until_expiry": 7,
    "issuer": "Let's Encrypt"
  },
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

Page Speed Alert

Page Speed Alert Payload

{
  "event": "page_speed",
  "timestamp": "2025-01-12T10:30:00Z",
  "website": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "performance": {
    "response_time": 5230,
    "threshold": 3000,
    "status": "slow"
  },
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

Dead Links Alert

Dead Links Alert Payload

{
  "event": "dead_links",
  "timestamp": "2025-01-12T10:30:00Z",
  "website": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "dead_links": {
    "count": 3,
    "links": [
      {
        "url": "https://example.com/broken-page",
        "status_code": 404,
        "found_on": "https://example.com/about"
      }
    ]
  },
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

Security

Webhook requests include a signature header for verification:

Signature Verification

X-Webhook-Signature: sha256=hash_value

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format.

200Success

400Bad Request

401Unauthorized

403Forbidden

404Not Found

429Rate Limited

500Server Error

Error Response Formats

Standard Errors

Error Response

{
  "error": "Error message describing what went wrong"
}

Validation Errors

Validation Error Response

{
  "error": "Invalid input",
  "details": [
    {
      "code": "invalid_type",
      "path": ["url"],
      "message": "Invalid URL format"
    }
  ]
}

Rate Limit Errors

Rate Limit Response

{
  "error": "Rate limit exceeded",
  "message": "Too many site creation requests. Please try again later.",
  "retryAfter": 3542,
  "limit": 10,
  "remaining": 0,
  "resetAt": "2025-01-15T11:30:00.000Z"
}

SDKs & Libraries

SDK Coming Soon! We're currently publishing our official SDK to npm. Check back in 24 hours!

Official SDKs and community libraries to integrate PingBuoy into your applications.

JavaScript/Node.js

Installation

npm install pingbuoy-sdk

View on GitHub

Python

Installation

pip install pingbuoy

View on GitHub

Go

Installation

go get github.com/pingbuoy/go-sdk

View on GitHub

PHP

Installation

composer require pingbuoy/php-sdk

View on GitHub

Need Help?

If you have questions about the API or need assistance with integration, our support team is here to help.

Contact Support

API Documentation

Complete API reference for PingBuoy monitoring service

Getting Started

The PingBuoy API allows you to programmatically manage your website monitoring, alerts, and integrations. Our REST API uses standard HTTP methods and returns JSON responses.

Base URL

https://pingbuoy.com/api

Quick Example

Get your monitored sites

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://pingbuoy.com/api/sites

Field Naming Conventions

The API uses different naming conventions for different resource types:

snake_caseUsed for Sites/Monitoring endpoints (matches database schema): last_checked, created_at, user_id

camelCaseUsed for Integrations/API Keys endpoints (JavaScript-friendly): lastUsed, createdAt, totalRequests

This intentional design provides optimal ergonomics for each API context while maintaining consistency within each resource type.

Authentication

PingBuoy uses API keys for authentication. Include your API key in the Authorization header of all requests.

Security Notice

Keep your API keys secure and never expose them in client-side code. Rotate keys regularly for enhanced security.

Creating API Keys

Generate API keys in your dashboard integrations page.

Using API Keys

Authentication Header

Authorization: Bearer pb_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345

Rate Limits

API requests are rate limited per operation type to ensure system stability and fair usage.

Operation	Rate Limit
Site creation/deletion	10 per hour
Integration operations	20 per hour
Manual monitoring triggers	10 per hour
Data exports	3 per hour

Site creation/deletion

Rate Limit10 per hour

Integration operations

Rate Limit20 per hour

Monitoring checks

Rate Limit100 per hour

Rate Limit Headers

All API responses include rate limit information in headers:

Response Headers

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 2025-01-15T11:00:00.000Z

Rate Limit Exceeded

When rate limited, the API returns HTTP 429 with a Retry-After header indicating seconds until reset.

Websites

GET

/api/sites

Retrieve all monitored sites

Parameters

Name	Type	Required	Description
status	string	Optional	Filter by status (up, down, unknown)

status

Typestring

RequiredNo

DescriptionFilter by status (up, down, unknown)

Response

[
  {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com",
    "type": "website",
    "status": "up",
    "last_checked": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "user_id": "uuid",
    "is_active": true
  }
]

Example

cURL Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/sites"

POST

/api/sites

Add a new site to monitor

Parameters

Name	Type	Required	Description
name	string	Required	Site display name (max 100 chars)
url	string	Required	Site URL to monitor (must be valid URL)
type	string	Optional	Site type: "website" or "api_endpoint" (default: "website")

name

Typestring

RequiredYes

DescriptionSite display name (max 100 chars)

url

Typestring

RequiredYes

DescriptionSite URL to monitor (must be valid URL)

type

Typestring

RequiredNo

DescriptionSite type: "website" or "api_endpoint" (default: "website")

Response

{
  "id": "uuid",
  "name": "My Website",
  "url": "https://example.com",
  "type": "website",
  "status": "unknown",
  "user_id": "uuid",
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "last_checked": null
}

Example

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Website", "url": "https://example.com", "type": "website"}' \
  https://pingbuoy.com/api/sites

DELETE

/api/sites?id={id}

Remove a site from monitoring

Parameters

Name	Type	Required	Description
id	string	Required	Site UUID (query parameter)

Typestring

RequiredYes

DescriptionSite UUID (query parameter)

Response

{
  "success": true
}

Example

cURL Example

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/sites?id=SITE_UUID"

Monitoring Data

POST

/api/monitoring/trigger

Manually trigger a monitoring check for a site

Parameters

Name	Type	Required	Description
action	string	Required	Check type: "uptime", "pagespeed", or "deadlinks"
siteId	string	Required	Site UUID to check

action

Typestring

RequiredYes

DescriptionCheck type: "uptime", "pagespeed", or "deadlinks"

siteId

Typestring

RequiredYes

DescriptionSite UUID to check

Response

{
  "success": true,
  "site": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "result": {
    "type": "uptime",
    "status": "up",
    "responseTime": 234,
    "statusCode": 200,
    "sslValid": true
  }
}

Example

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "uptime", "siteId": "SITE_UUID"}' \
  https://pingbuoy.com/api/monitoring/trigger

GET

/api/integrations

Get all your integrations (Slack, Discord, Webhooks)

Response

[
  {
    "id": "uuid",
    "name": "Slack Alerts",
    "type": "slack",
    "status": "active",
    "config": {
      "events": ["downtime", "recovery"]
    },
    "lastTest": "2025-01-15T10:30:00Z",
    "lastTestStatus": "success",
    "totalNotifications": 42
  }
]

Example

cURL Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/integrations"

POST

/api/integrations

Create a new integration

Parameters

Name	Type	Required	Description
name	string	Required	Integration name (max 100 chars)
integration_type	string	Required	Type: slack, discord, or webhook
webhook_url	string	Required	Webhook URL (must be valid URL format)
events	array	Optional	Events to monitor (downtime, recovery, page_speed, ssl_expiration, dead_links (default: all events))

name

Typestring

RequiredYes

DescriptionIntegration name (max 100 chars)

integration_type

Typestring

RequiredYes

DescriptionType: slack, discord, or webhook

webhook_url

Typestring

RequiredYes

DescriptionWebhook URL (must be valid URL format)

events

Typearray

RequiredNo

DescriptionEvents to monitor (downtime, recovery, page_speed, ssl_expiration, dead_links (default: all events))

Response

{
  "success": true,
  "integration": {
    "id": "uuid",
    "name": "My Slack Integration",
    "type": "slack",
    "status": "active",
    "config": {
      "events": ["downtime", "recovery", "ssl_expiry"]
    }
  }
}

Example

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Alerts",
    "integration_type": "slack",
    "webhook_url": "https://hooks.slack.com/services/...",
    "events": ["downtime", "recovery"]
  }' \
  https://pingbuoy.com/api/integrations

DELETE

/api/integrations?id={id}

Delete an integration

Parameters

Name	Type	Required	Description
id	string	Required	Integration UUID (query parameter)

Typestring

RequiredYes

DescriptionIntegration UUID (query parameter)

Response

{
  "success": true
}

Example

cURL Example

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/integrations?id=INTEGRATION_UUID"

API Keys

GET

/api/keys

Get all your API keys

Response

[
  {
    "id": "uuid",
    "name": "Production API Key",
    "prefix": "pb_12345",
    "permissions": ["read", "write"],
    "status": "active",
    "totalRequests": 1234,
    "lastUsed": "2025-01-15T10:30:00Z",
    "createdAt": "2025-01-01T00:00:00Z"
  }
]

Example

cURL Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/keys"

POST

/api/keys

Generate a new API key

Parameters

Name	Type	Required	Description
name	string	Required	API key name (max 100 chars)
permissions	array	Required	Array of permissions (at least 1 required): ["read"], ["read", "write"], or ["read", "write", "admin"]

name

Typestring

RequiredYes

DescriptionAPI key name (max 100 chars)

permissions

Typearray

RequiredYes

DescriptionArray of permissions (at least 1 required): ["read"], ["read", "write"], or ["read", "write", "admin"]

Response

{
  "success": true,
  "key": "pb_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345",
  "apiKey": {
    "id": "uuid",
    "name": "My API Key",
    "prefix": "pb_12345",
    "permissions": ["read", "write"],
    "status": "active"
  }
}

Example

cURL Example

curl -X POST \
  -H "Authorization: Bearer YOUR_EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "permissions": ["read", "write"]
  }' \
  https://pingbuoy.com/api/keys

DELETE

/api/keys?id={id}

Revoke an API key

Parameters

Name	Type	Required	Description
id	string	Required	API key UUID (query parameter)

Typestring

RequiredYes

DescriptionAPI key UUID (query parameter)

Response

{
  "success": true
}

Example

cURL Example

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://pingbuoy.com/api/keys?id=KEY_UUID"

Webhooks

Webhooks allow you to receive real-time notifications when incidents occur. PingBuoy will send HTTP POST requests to your configured endpoints.

Webhook Payload

Downtime Alert Payload

{
  "event": "website.down",
  "timestamp": "2025-01-12T10:30:00Z",
  "website": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "incident": {
    "id": "uuid",
    "status_code": 503,
    "response_time": null,
    "error_message": "Service Unavailable"
  },
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

All Webhook Events

PingBuoy sends webhooks for the following event types:

Recovery Alert

Recovery Alert Payload

{
  "event": "website.recovery",
  "timestamp": "2025-01-12T10:35:00Z",
  "website": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "incident": {
    "id": "uuid",
    "downtime_duration_seconds": 300,
    "status_code": 200,
    "response_time": 234
  },
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

SSL Expiration Warning

SSL Expiration Warning Payload

{
  "event": "ssl_expiration",
  "timestamp": "2025-01-12T10:30:00Z",
  "website": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "ssl": {
    "expires_at": "2025-01-20T00:00:00Z",
    "days_until_expiry": 7,
    "issuer": "Let's Encrypt"
  },
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

Page Speed Alert

Page Speed Alert Payload

{
  "event": "page_speed",
  "timestamp": "2025-01-12T10:30:00Z",
  "website": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "performance": {
    "response_time": 5230,
    "threshold": 3000,
    "status": "slow"
  },
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

Dead Links Alert

Dead Links Alert Payload

{
  "event": "dead_links",
  "timestamp": "2025-01-12T10:30:00Z",
  "website": {
    "id": "uuid",
    "name": "My Website",
    "url": "https://example.com"
  },
  "dead_links": {
    "count": 3,
    "links": [
      {
        "url": "https://example.com/broken-page",
        "status_code": 404,
        "found_on": "https://example.com/about"
      }
    ]
  },
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

Security

Webhook requests include a signature header for verification:

Signature Verification

X-Webhook-Signature: sha256=hash_value

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format.

200Success

400Bad Request

401Unauthorized

403Forbidden

404Not Found

429Rate Limited

500Server Error

Error Response Formats

Standard Errors

Error Response

{
  "error": "Error message describing what went wrong"
}

Validation Errors

Validation Error Response

{
  "error": "Invalid input",
  "details": [
    {
      "code": "invalid_type",
      "path": ["url"],
      "message": "Invalid URL format"
    }
  ]
}

Rate Limit Errors

Rate Limit Response

{
  "error": "Rate limit exceeded",
  "message": "Too many site creation requests. Please try again later.",
  "retryAfter": 3542,
  "limit": 10,
  "remaining": 0,
  "resetAt": "2025-01-15T11:30:00.000Z"
}

SDKs & Libraries

SDK Coming Soon! We're currently publishing our official SDK to npm. Check back in 24 hours!

Official SDKs and community libraries to integrate PingBuoy into your applications.

JavaScript/Node.js

Installation

npm install pingbuoy-sdk

View on GitHub

Python

Installation

pip install pingbuoy

View on GitHub

Go

Installation

go get github.com/pingbuoy/go-sdk

View on GitHub

PHP

Installation

composer require pingbuoy/php-sdk

View on GitHub

Need Help?

If you have questions about the API or need assistance with integration, our support team is here to help.

Contact Support

API Documentation

Contents

API Status

Getting Started

Base URL

Quick Example

Field Naming Conventions

Authentication

Security Notice

Creating API Keys

Using API Keys

Rate Limits

Rate Limit Headers

Rate Limit Exceeded

Websites

/api/sites

Parameters

Response

Example

/api/sites

Parameters

Response

Example

/api/sites?id={id}

Parameters

Response

Example

Monitoring Data

/api/monitoring/trigger

Parameters

Response

Example

/api/integrations

Response

Example

/api/integrations

Parameters

Response

Example

/api/integrations?id={id}

Parameters

Response

Example

API Keys

/api/keys

Response

Example

/api/keys

Parameters

Response

Example

/api/keys?id={id}

Parameters

Response

Example

Webhooks

Webhook Payload

All Webhook Events

Recovery Alert

SSL Expiration Warning

Page Speed Alert

Dead Links Alert

Security

Error Handling

Error Response Formats

Standard Errors

Validation Errors

Rate Limit Errors

SDKs & Libraries

JavaScript/Node.js

Python

Go

PHP

Need Help?

Loading

API Documentation

Contents

API Status

Getting Started

Base URL