Authentication

The PingFlow REST API allows you to programmatically access our global network sensors. API access is restricted to PingFlow PRO members.

Getting your API Key

Once you have upgraded to PRO, navigate to your Account Profile. Under the "Developer settings" tab, you can generate a new Bearer Token.

Your API key carries the same privileges as your user account. Keep it secret. Do not expose it in client-side code (like frontend JavaScript) or public GitHub repositories.

Authenticating Requests

Authenticate your API requests by including your API key in the `Authorization` HTTP header as a Bearer token.

curl -X GET "https://pingflow.online/api/v1/dns?domain=example.com" \
  -H "Authorization: Bearer pf_live_abc123def456ghi789" \
  -H "Content-Type: application/json"

If you fail to include the header, or if the token is invalid or expired, the API will return a 401 Unauthorized HTTP response.

Rate Limits

To ensure global stability and prevent abuse of our sensor network, the PingFlow API is rate-limited. Limits differ based on your account tier.

Account Tiers

Rate Limit Headers

Every API response includes standard HTTP headers detailing your current rate limit status:

• X-RateLimit-Limit: The maximum number of requests you're permitted to make per minute.
• X-RateLimit-Remaining: The number of requests remaining in the current window.
• X-RateLimit-Reset: The time at which the current rate limit window resets in UTC epoch seconds.

Errors & Status Codes

PingFlow uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with PingFlow's servers.

SDKs & Libraries

To make integrating with PingFlow as fast as possible, we provide official libraries for popular languages.

Node.js (NPM)

Install via npm:

npm install pingflow-node

Usage:

import { PingFlow } from 'pingflow-node';

const pf = new PingFlow('YOUR_API_KEY');

// Fetch DNS Records
const records = await pf.dns.lookup('github.com');
console.log(records.A);

Python (PIP)

Install via pip:

pip install pingflow-py

Usage:

import pingflow

pf = pingflow.Client(api_key="YOUR_API_KEY")

# Check Global Status
status = pf.status.get_service("aws")
print(f"AWS is currently {status.current_status}")

Global Status API

Fetch real-time latency and historical uptime data for over 100+ monitored internet services.

GET /api/history/:serviceId

Retrieves the live status and a 40-tick historical array for the specified service. Valid service IDs include aws, cloudflare, chatgpt, discord, etc.

Example Request

const response = await fetch('https://pingflow.online/api/history/aws', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_PRO_KEY'
  }
});
const data = await response.json();

Example JSON Response

{
  "service": "aws",
  "currentStatus": "operational",
  "history": [
    {
      "timestamp": "2026-05-11T14:28:00Z",
      "online": true,
      "latency": 42
    },
    // ... 39 more historical data points
  ]
}

DNS Intelligence API

Programmatically execute DNS queries against PingFlow's infrastructure.

POST /api/dns-lookup

Execute a DNS resolution request. You must pass a JSON body containing the target domain.

Example Request

curl -X POST "https://pingflow.online/api/dns-lookup" \
  -H "Authorization: Bearer YOUR_PRO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "github.com" }'

Example JSON Response

{
  "success": true,
  "domain": "github.com",
  "records": {
    "A": ["140.82.113.3"],
    "MX": [
      { "exchange": "alt1.aspmx.l.google.com", "priority": 10 }
    ]
  },
  "executionTimeMs": 14
}

Port Scanner API

Scan TCP ports on remote servers to verify firewall configurations and exposed services.

POST /api/port-scan

Provide a target IP or domain, and an array of ports to scan. The system will attempt a 2-second TCP handshake on each.

Example Request Body

{
  "target": "185.249.75.79",
  "ports": [80, 443, 22, 3306]
}

Example JSON Response

{
  "target": "185.249.75.79",
  "results": [
    { "port": 80, "status": "open", "service": "http" },
    { "port": 443, "status": "open", "service": "https" },
    { "port": 22, "status": "filtered", "service": "ssh" },
    { "port": 3306, "status": "closed", "service": "mysql" }
  ]
}

Account API

Programmatically access details about your authenticated user profile, including your current Knowledge Points (KP) and PRO status.

GET /api/v1/account/me

Retrieves the profile data of the API key owner.

Example Request

curl -X GET "https://pingflow.online/api/v1/account/me" \
  -H "Authorization: Bearer YOUR_PRO_KEY"

Example JSON Response

{
  "id": "usr_987654321",
  "email": "dev@example.com",
  "name": "NodeHunter",
  "isPro": true,
  "points": 124500,
  "activeIcon": "badge_dev"
}

Outage Webhooks PRO

Instead of polling the API, PingFlow can push real-time outage alerts directly to your servers or chat applications (like Discord or Slack).

Setup

Navigate to your PRO dashboard and enter a valid HTTPS URL in the Webhooks field. You can configure it to trigger on All Services, or specify an array of specific IDs (e.g., just AWS and Cloudflare).

Payload Structure

When an outage is detected (or resolved), PingFlow will send a POST request to your URL with the following JSON body:

{
  "event": "incident.detected", // or "incident.resolved"
  "service_id": "aws",
  "service_name": "AWS Route53",
  "timestamp": "2026-05-11T14:28:00Z",
  "details": "PingFlow sensors detected 100% packet loss to aws.amazon.com over a 30 second window."
}

Discord Integration

PingFlow payloads are natively formatted to support Discord Webhooks. Simply paste your Discord channel Webhook URL into the dashboard, and PingFlow will automatically format the JSON into a beautiful Discord Embed card!

WebSocket API PRO

For applications that require ultra-low latency updates without the overhead of HTTP polling, you can connect directly to the PingFlow WebSocket stream.

WSS wss://pingflow.online/live

To authenticate, append your API key as a query parameter during the initial handshake.

Example Connection (Browser JS)

const ws = new WebSocket('wss://pingflow.online/live?token=YOUR_PRO_KEY');

ws.onopen = () => {
  console.log('Connected to PingFlow Telemetry Stream');
};

ws.onmessage = (event) => {
  const telemetry = JSON.parse(event.data);
  console.log(`Live Latency for ${telemetry.service}: ${telemetry.latency}ms`);
};

Event Types

The WebSocket server pushes two types of events:

• telemetry_tick: Emitted every time a node completes a ping check against a monitored service.
• global_alert: Emitted when the master engine detects a major infrastructure shift or regional outage.