Skip to main content

​
PulseGuard API

The PulseGuard API provides programmatic access to all monitoring features, allowing you to integrate monitoring capabilities into your applications, automate workflows, and build custom dashboards.

​
Base URL

https://api.ipulse.one
All API requests must be made over HTTPS. HTTP requests will be redirected to HTTPS.

​
Authentication

The PulseGuard API uses Bearer token authentication. You can obtain an API key from your dashboard or use JWT tokens from Clerk authentication. 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.ipulse.one/api/domains

​
API Playground

You can test all API endpoints directly in your browser with our interactive playground. All examples include authentication and can be run immediately. The playground includes:
  • Live API calls with your authentication
  • Request/response examples in multiple languages
  • Schema validation for all parameters
  • Error simulation for testing error handling

​
Rate Limits

API rate limits vary by endpoint and authentication method:
Endpoint TypeAPI Key LimitJWT Token Limit
Read operations1000/hour5000/hour
Write operations100/hour1000/hour
Bulk operations10/hour50/hour
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​
Response Format

All API responses follow a consistent JSON format: 
{
  "data": { ... },
  "pagination": { ... },
  "meta": { ... }
}
Error responses include detailed error information: 
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid domain URL format",
  "details": {
    "field": "url",
    "reason": "URL must include protocol (http/https)"
  }
}

​
SDKs and Libraries

​
Official SDKs

npm install @pulseguard/sdk

​
Community SDKs

​
Quick Start

  1. Get an API Key
    • Log in to your PulseGuard dashboard
    • Go to Settings → API Keys
    • Click “Generate New Key”
  2. Make your first request 
    curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.ipulse.one/api/domains
  3. Create your first domain 
    curl -X POST "https://api.ipulse.one/api/domains" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "name": "My Website"
  }'

​
API Versions

The current API version is v1. All endpoints are backward compatible within major versions. API versioning is handled through URL paths:
  • Current: https://api.ipulse.one/api/...
  • Future v2: https://api.ipulse.one/v2/api/...

​
Webhooks

PulseGuard supports webhooks for real-time notifications. Configure webhooks to receive events when:
  • Domains go up/down
  • SSL certificates expire
  • Incidents are created/resolved
  • Maintenance windows start/end

​
Webhook Configuration

{
  "url": "https://your-app.com/webhooks/pulseguard",
  "events": ["domain_up", "domain_down", "incident_created"],
  "secret": "your_webhook_secret"
}

​
Webhook Payload

{
  "event": "domain_down",
  "timestamp": "2024-01-17T10:30:00Z",
  "data": {
    "domain_id": "domain_123",
    "url": "https://example.com",
    "status": "down",
    "response_time_ms": null,
    "error": "Connection timeout"
  }
}

​
Error Handling

Implement proper error handling for all API requests: 
async function apiRequest(endpoint, options = {}) {
  try {
    const response = await fetch(`https://api.ipulse.one${endpoint}`, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
        ...options.headers
      },
      ...options
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`${error.error}: ${error.message}`);
    }

    return await response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

​
Support

​
Getting Help

  • Documentation: Complete API reference with examples
  • API Playground: Interactive testing environment
  • Community Forums: Peer support and discussions
  • Support Portal: Priority support for paid plans

​
Common Issues

401 Unauthorized
  • Check your API key is correct and not expired
  • Ensure the Authorization header is properly formatted
429 Too Many Requests
  • Implement exponential backoff
  • Check rate limit headers in responses
  • Upgrade to higher plan if needed
500 Internal Server Error
  • Retry with exponential backoff
  • Check the PulseGuard status page for outages
  • Contact support if the issue persists

​
Changelog

​
v1.0.0 (Current)

  • Initial release of PulseGuard API
  • Full CRUD operations for domains, services, devices
  • Comprehensive monitoring statistics
  • Webhook support for real-time notifications
  • Interactive API playground

​
Upcoming Features

  • GraphQL API (Q2 2024)
  • Bulk operations for large datasets
  • Advanced filtering and search
  • Real-time WebSocket connections
  • Enhanced AI insights API