PureGuard API Documentation

PureGuard is a server-side bot detection engine built for performance media buyers. It analyzes every click through 13+ configurable detection layers and returns a verdict in under 15ms. This documentation covers the REST API, detection engine internals, and integration guides for every major traffic source.

Quick start: Sign up, grab your API key from the Dashboard, and send your first bot check request in under 60 seconds.

1. Create an account

Register for free to get instant access. Your starter plan includes 100,000 bot checks per month at no cost. No credit card required.

2. Get your API key

After logging in, navigate to Settings to find your API key. The key is a unique string prefixed with pg_ that authenticates all your requests.

3. Make your first request

cURL

curl -X POST https://pureguard.io/api/v1/check \
  -H "X-API-Key: pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "1.2.3.4",
    "ua": "Mozilla/5.0 Chrome/131.0",
    "url": "https://example.com/offer"
  }'

The response tells you whether to accept or block the visitor:

Response

{
  "verdict": "ACCEPT",
  "trust": 7.3,
  "confidence": 92,
  "signals": ["browser_valid:+bonus", "network:+bonus", "device:+bonus"],
  "ms": 2.3
}

Authentication

All API requests (except GET /api/v1/status) require authentication via the X-API-Key header. Your API key is available on the Settings page of your dashboard.

Keep your key secret. Do not expose it in client-side JavaScript. PureGuard is designed for server-to-server calls only. If your key is compromised, regenerate it immediately from Settings.

Header	Value	Required
X-API-Key	pg_xxxxxxxxxxxxxxxx	Required
Content-Type	application/json	Required (for POST)

Example authenticated request:

cURL

curl -H "X-API-Key: pg_abc123def456" \
     https://pureguard.io/api/v1/stats

Requests without a valid key receive a 401 Unauthorized response. Requests that exceed your plan's monthly quota receive 429 Too Many Requests.

API Reference

Base URL: https://pureguard.io/api/v1. All request and response bodies use JSON. Times are in UTC.

Bot Check

POST /api/v1/check

Evaluate a single visitor. Send the visitor's IP address, user-agent string, and optionally their HTTP headers for maximum detection accuracy. The engine runs all enabled layers and returns a verdict within milliseconds.

Request Body

Field	Type	Required	Description
ip	string	Required	Visitor's IPv4 or IPv6 address
ua	string	Required	Raw User-Agent header string
url	string	Required	Destination URL (the page they would see)
headers	object	Optional	Full HTTP headers map. Enables Sec-Fetch, Accept-Language, and header fingerprint layers
zone	string	Optional	Traffic source zone/site ID for zone reputation scoring

Full Example

Request

POST /api/v1/check HTTP/1.1
Host: pureguard.io
X-API-Key: pg_abc123def456
Content-Type: application/json

{
  "ip": "203.0.113.42",
  "ua": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Mobile Safari/537.36",
  "url": "https://example.com/offer?s1=zone_1234",
  "headers": {
    "Sec-Fetch-Site": "cross-site",
    "Sec-Fetch-Mode": "navigate",
    "Sec-Fetch-Dest": "document",
    "Accept-Language": "th-TH,th;q=0.9,en;q=0.8",
    "Accept-Encoding": "gzip, deflate, br"
  },
  "zone": "zone_1234"
}

Response -- 200 OK

{
  "verdict": "ACCEPT",
  "trust": 7.3,
  "confidence": 92,
  "signals": [
    "browser_valid:+bonus",
    "network:+bonus",
    "device_auth:+bonus",
    "protocol:+bonus",
    "geo_match:+bonus"
  ],
  "ms": 2.3
}

Response Fields

Field	Type	Description
verdict	string	`"ACCEPT"` or `"BLOCK"` -- the final decision
trust	float	Trust score from 0.0 (definite bot) to 10.0 (definite human)
confidence	integer	Engine confidence in the verdict, 0-100. Higher means more signals evaluated
signals	array	List of detection signals that fired, with their score impact (e.g. `"threat_intel:KILL"`)
ms	float	Processing time in milliseconds

Blocked response example: When a bot is detected, the response contains the kill reason: {"verdict":"BLOCK","trust":0.0,"confidence":99,"signals":["threat_intel:KILL"],"ms":0.8}

Traffic Statistics

GET /api/v1/stats

Returns aggregated traffic statistics for your account. Includes today's counts and a 7-day historical breakdown for charting.

Response -- 200 OK

{
  "today": {
    "checks": 14832,
    "accepts": 8291,
    "blocks": 6541,
    "rate": 55.9
  },
  "week": [
    { "date": "2026-03-02", "checks": 12480, "accepts": 7120, "blocks": 5360 },
    { "date": "2026-03-03", "checks": 13105, "accepts": 7402, "blocks": 5703 },
    { "date": "2026-03-04", "checks": 11893, "accepts": 6814, "blocks": 5079 },
    { "date": "2026-03-05", "checks": 14220, "accepts": 7988, "blocks": 6232 },
    { "date": "2026-03-06", "checks": 15010, "accepts": 8201, "blocks": 6809 },
    { "date": "2026-03-07", "checks": 13744, "accepts": 7512, "blocks": 6232 },
    { "date": "2026-03-08", "checks": 14832, "accepts": 8291, "blocks": 6541 }
  ]
}

Zone Data

GET /api/v1/zones

Returns zone reputation data for all zones seen in your traffic. Use this to identify high-quality and toxic traffic sources programmatically.

Response -- 200 OK

{
  "zones": [
    {
      "id": "zone_1234",
      "status": "trusted",
      "score": 8.2,
      "hits": 4521,
      "accept_rate": 87.3,
      "webview_rate": 2.1,
      "hosting_rate": 0.5,
      "deprecated_rate": 1.3,
      "pattern_penalty": 0.8,
      "ua_monoculture": 12.4,
      "trust_stdev": 1.92,
      "hugger_rate": 3.2,
      "unique_uas": 387
    },
    {
      "id": "zone_5678",
      "status": "blocked",
      "score": 1.4,
      "hits": 892,
      "accept_rate": 12.1,
      "webview_rate": 38.7,
      "hosting_rate": 62.3,
      "deprecated_rate": 45.1,
      "pattern_penalty": 28.5,
      "ua_monoculture": 78.9,
      "trust_stdev": 0.41,
      "hugger_rate": 67.2,
      "unique_uas": 3
    },
    {
      "id": "zone_9012",
      "status": "neutral",
      "score": 5.0,
      "hits": 38,
      "accept_rate": 63.2,
      "webview_rate": 8.4,
      "hosting_rate": 5.2,
      "deprecated_rate": 6.1,
      "pattern_penalty": 4.2,
      "ua_monoculture": 25.0,
      "trust_stdev": 1.58,
      "hugger_rate": 12.8,
      "unique_uas": 14
    }
  ]
}

Zone Statuses

Status	Meaning
trusted	Zone has high accept rate and human evidence. Elite traffic.
neutral	New zone or insufficient data to classify. In probation.
blocked	Zone consistently sends bot traffic. All hits from this zone are rejected.

Pattern Intelligence Fields

Each zone includes pattern intelligence signals that reveal bot behavior patterns beyond simple accept/block rates. These fields are computed from traffic analysis and help identify sophisticated bot farms.

Field	Type	Description
`webview_rate`	float	Percentage of hits from Android WebView (UA contains "Version/4.0" + "Android"). High rates (>20%) indicate in-app ad fraud -- programmatic clicks inside embedded browsers, not real user navigation.
`hosting_rate`	float	Percentage of hits from hosting/cloud ASNs (AWS, GCP, Azure, DigitalOcean, OVH, etc.) detected via MaxMind ASN database. Real users browse from residential ISPs, not server farms. Rates >10% are suspicious.
`deprecated_rate`	float	Percentage of hits with "; U;" in the User-Agent string. This token was deprecated from Chrome UAs in 2010 (Chrome 6+). Its presence indicates outdated/recycled bot UA strings. Any rate above 5% is a strong bot signal.
`pattern_penalty`	float	Combined penalty score (0-100) from all pattern signals: webview, hosting, deprecated UA, monoculture, and threshold-hugger analysis. Higher values indicate more bot-like patterns. Zones above 15 warrant investigation.
`ua_monoculture`	float	Percentage of hits sharing the single most common User-Agent string. Real traffic shows natural UA diversity (typically 5-15% monoculture). Bot farms reuse the same UA, producing values >50%. Adjusted for Chrome 110+ UA Reduction.
`trust_stdev`	float	Standard deviation of trust scores within the zone. Real traffic has natural variance (stdev 1.0-3.0). Bot farms produce uniform scores (stdev <0.5), while a mix of bots and humans produces high variance (>3.0).
`hugger_rate`	float	Percentage of hits with trust scores within 0.5 of the block threshold. "Threshold huggers" are sophisticated bots calibrated to barely pass the filter. Rates >30% indicate deliberate trust-score manipulation.
`unique_uas`	integer	Count of distinct User-Agent strings seen from this zone. Combined with `ua_monoculture`, this reveals traffic diversity. A zone with 500 hits but only 3 unique UAs is almost certainly a bot farm.

System Status

GET /api/v1/status

Public endpoint (no authentication required). Returns current engine status, version, and uptime. Use this for health checks and monitoring.

Response -- 200 OK

{
  "status": "operational",
  "engine": "v17.1",
  "layers": 13,
  "uptime": 99.7
}

Detection Layers

PureGuard's engine evaluates traffic through multiple independent detection layers. Each layer operates in one of three modes:

Kill -- Instant block. A single confirmed signal is enough to reject the visitor.
Score -- Adjusts the trust score up or down. Multiple weak signals compound.
Observe -- Logs the signal for analysis but does not affect the verdict.

All layers are fully configurable through the dashboard. You can enable/disable individual layers and change their mode via the Guard Settings panel.

Hard Kill Layers

These layers terminate evaluation immediately when triggered. A single match means definite bot.

IP Threat Intelligence Kill

Checks the visitor's IP against the multiple curated threat intelligence feeds covering hundreds of millions of known malicious IPs. Updated continuously from global sensor networks.

Signal: threat_intel:KILL

Community Threat Network Kill

Community-driven threat intelligence network. Blocks IPs flagged by a global network of sensor machines for scanning, brute-force, and automated abuse.

Signal: community_threat:KILL

Bot UA Detection Kill

Pattern-matches the User-Agent against known bot signatures: 200+ known automation frameworks, headless browsers, scraping tools, and bot crawlers.

Signal: bot_ua:KILL

Chrome Version Check Kill

Blocks UAs claiming Chrome versions beyond 160 -- no such version exists. Bots often generate random high version numbers to appear "modern."

Signal: fake_chrome:KILL

Browser Build Verification Kill

Detects Chrome UA Reduction abuse. Chrome 110+ legitimately sends .0.0.0 build numbers, but older Chrome versions with .0.0.0 are spoofed bots impersonating the UA Reduction format.

Signal: build_verify:KILL

Burst Rate Limiter Kill

Blocks IPs that exceed the burst threshold (configurable, default: 5 hits per minute). Uses in-memory counters for sub-millisecond lookups with no database overhead.

Signal: burst_rate:KILL

Ad-Fraud UA Signatures Kill

Identifies ad verification and fraud detection crawlers: known ad verification crawlers, fraud detection spiders, and ad-tech measurement bots.

Signal: adfraud_ua:KILL

Trust Scoring Layers

These layers adjust the trust score (proprietary base) up or down. Multiple signals compound. The final trust score determines the verdict: below threshold = BLOCK, above = ACCEPT.

Sec-Fetch Headers Score

Analyzes browser-enforced Sec-Fetch-Site, Sec-Fetch-Mode, and Sec-Fetch-Dest headers. These headers cannot be spoofed by JavaScript and are only sent by real browsers.

Valid: bonus | Missing: penalty | Invalid: minor penalty

Datacenter ASN Detection Score

Checks the visitor's IP against 11,600+ known hosting, datacenter, and cloud ASNs from a proprietary database. Real users browse from residential or mobile networks, not datacenters.

Datacenter: penalty | Residential: minor bonus

Header Consistency Score

Validates expected HTTP header patterns: missing Accept-Encoding (bots skip it), Connection:close (browsers use keep-alive), and Chrome 89+ without Sec-CH-UA (Client Hints are mandatory in modern Chrome).

No Accept-Encoding: penalty | Connection:close: penalty | No Sec-CH-UA: penalty

Referer Analysis Score

Penalizes empty referer headers from RTB traffic sources. Real pop/push traffic always includes a referer from the publisher site.

Empty referer (RTB): penalty

HTTP Version Check Score

Chrome 80+ should use HTTP/2 or HTTP/1.1. If the request arrives as HTTP/1.0 with a modern Chrome UA, it is likely a proxy or script, not a real browser.

Chrome 80+ on HTTP/1.0: penalty

Hosting ASN Detection Score

Uses proprietary ASN intelligence to identify hosting, VPN, and proxy providers at the ASN level. Covers 11,600+ hosting networks including smaller VPS providers and commercial VPNs.

Hosting ASN: penalty

Observation Layers

These layers collect signals for analysis and reporting but do not affect the verdict by default. Enable scoring mode on any of them to start using them in decisions.

Language Check Observe

Compares the Accept-Language header against the visitor's geo-IP country. Includes an exception list of 26 countries where English is commonly used alongside local languages (SEA, India, parts of Africa).

Logs: lang_primary, lang_match

Header Fingerprint Observe

Computes a fingerprint of the HTTP header order. Real browsers send headers in a consistent, browser-specific order. Automated tools and proxies produce different orderings.

Logs: header_fingerprint

TLS Fingerprint Observe

Records the TLS version from Cloudflare's CF-TLS-Version header. Modern browsers use TLS 1.3. Older TLS versions correlate with outdated or automated clients.

Logs: cf_tls_version

Integration Guide

PureGuard integrates into any stack. Below are production-ready examples for the most common languages, plus traffic source and RTB setup instructions.

PHP Integration

Direct server-side integration. Call the API before redirecting the visitor.

guard_check.php

<?php
function checkBot($ip, $ua, $url, $headers = []) {
    $ch = curl_init('https://pureguard.io/api/v1/check');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 5,
        CURLOPT_HTTPHEADER     => [
            'X-API-Key: pg_your_api_key',
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'ip'      => $ip,
            'ua'      => $ua,
            'url'     => $url,
            'headers' => $headers,
        ]),
    ]);

    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $response;
}

// Usage in your click handler:
$result = checkBot(
    $_SERVER['REMOTE_ADDR'],
    $_SERVER['HTTP_USER_AGENT'],
    'https://example.com/offer'
);

if ($result['verdict'] === 'BLOCK') {
    http_response_code(204);  // Bot killed silently
    exit;
}

// Clean visitor -- redirect to offer
header('Location: https://offer.example.com/lp1');
exit;

Node.js Integration

guard.js

const checkBot = async (ip, ua, url) => {
  const res = await fetch('https://pureguard.io/api/v1/check', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.PUREGUARD_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ ip, ua, url }),
  });

  return res.json();
};

// Express middleware example
app.get('/click', async (req, res) => {
  const guard = await checkBot(
    req.ip,
    req.get('User-Agent'),
    req.originalUrl
  );

  if (guard.verdict === 'BLOCK') {
    return res.status(204).end();
  }

  res.redirect('https://offer.example.com/lp1');
});

Python Integration

guard.py

import requests
import os

API_KEY = os.getenv("PUREGUARD_KEY")
API_URL = "https://pureguard.io/api/v1/check"

def check_bot(ip: str, ua: str, url: str) -> dict:
    resp = requests.post(
        API_URL,
        json={"ip": ip, "ua": ua, "url": url},
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json",
        },
        timeout=5,
    )
    resp.raise_for_status()
    return resp.json()

# Usage with Flask
from flask import Flask, request, redirect, abort

app = Flask(__name__)

@app.route("/click")
def click_handler():
    result = check_bot(
        request.remote_addr,
        request.user_agent.string,
        request.url,
    )
    if result["verdict"] == "BLOCK":
        abort(204)
    return redirect("https://offer.example.com/lp1")

Traffic Source Setup

For pop/push/native traffic sources, point your campaign URL through PureGuard's click handler. The engine evaluates the visitor inline and redirects clean traffic to your offer.

Redirect flow: Traffic Source → click.php (Guard evaluates) → ACCEPT: 302 to your offer URL | BLOCK: 302 to dump URL

Click URL Format

Campaign URL

https://pureguard.io/click.php?wk={workspace_key}&s1={zone_id}&s2={click_id}&s3={source}

Source Macro Mapping

Source	s1 (Zone)	s2 (Click ID)	s3 (Source)
pop networks	`[WEBSITEID]`	`[IMPRESSIONID]`	`POPADS`
pop networks	`${SITE_ID}`	`${CLICK_ID}`	`ROLLERADS`
premium pop networks	`{{zoneid}}`	`{{clickid}}`	`HILLTOPADS`
premium networks	`{source}`	`{cid}`	`ZEROPARK`
ExoClick	`{zone_id}`	`{conversions_tracking}`	`EXOCLICK`

RTB / OpenRTB 2.5

PureGuard includes a built-in OpenRTB 2.5 bidder for programmatic traffic. The RTB endpoint evaluates bid requests through a dedicated Guard RTB pipeline with dozens of signals optimized for bid-time decisions (no browser headers available).

RTB Bid Endpoint

// SSP sends bid request to:
POST https://pureguard.io/bid.php

// PureGuard responds with:
//   BID   (above threshold)  -> 200 with bid response
//   NOBID (below threshold)  -> 204 No Content

// Win notice URL (in bid response):
https://pureguard.io/win.php?price=${AUCTION_PRICE}&id={bid_id}

RTB Trust Engine

The RTB pipeline starts at a base trust score and applies multiple penalty/bonus signals. Traffic scoring at bid time does not have access to browser headers (Sec-Fetch, etc.) since the RTB request comes from the SSP server, not the end user. Instead it relies on:

IP blocklist checks (multiple threat intelligence feeds)
UA pattern matching (bot signatures, ad-fraud crawlers)
Device type analysis (connected TV, set-top box penalties)
Geo verification (cross-check vs declared geo)
Domain quality (junk domains, IP-as-domain, ad-heavy TLDs)
Bid floor analysis (scam floors > $3, suspicious zero floors)
Burst rate limiting (in-memory, per-IP)

Daily budget: The RTB bidder enforces a configurable daily spend cap. When the budget is exhausted, all bid requests receive an instant 204 (no processing overhead).

Bid Request Format (OpenRTB 2.5)

Send a POST request with a JSON body conforming to OpenRTB 2.5:

Example Bid Request

{
  "id": "request-123",
  "imp": [{
    "id": "1",
    "instl": 1,
    "bidfloor": 0.50,
    "banner": { "topframe": 1 },
    "ext": { "type": "pop" }
  }],
  "site": {
    "domain": "example.com",
    "id": "site_456",
    "page": "https://example.com/page"
  },
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 14; ...) Chrome/131.0...",
    "ip": "203.0.113.42",
    "devicetype": 2,
    "os": "Android",
    "geo": { "country": "US" }
  },
  "at": 1,
  "cur": ["USD"]
}

Bid Response Format (200 OK)

When Guard accepts the traffic (above acceptance threshold), PureGuard returns a bid:

Example Bid Response

{
  "id": "request-123",
  "seatbid": [{
    "bid": [{
      "id": "bid-abc123",
      "impid": "1",
      "price": 0.501,
      "adm": "https://pureguard.io/click.php?s1={zone}&s3=SSP&...",
      "nurl": "https://pureguard.io/win.php?bid=bid-abc123&price=${AUCTION_PRICE}&req=request-123&zone={zone}&ssp=SSP",
      "adomain": ["pureguard.io"],
      "crid": "pop-1"
    }]
  }],
  "cur": "USD"
}

No-Bid Response (204 No Content)

A 204 response means PureGuard declined to bid. Common reasons:

Reason	Description
Budget exhausted	Daily spend cap reached (instant 204, no processing)
Low trust	Trust score below acceptance threshold
Bot UA	Known bot/crawler user agent detected
IP blocklist	IP found in threat intelligence blocklists
Blocked site	Site/zone on the iframe or quality blocklist
Geo mismatch	Declared geo doesn’t match IP-based geo
instl=0	Non-interstitial placement (pop requires instl=1)

Win Notice

The nurl field in the bid response contains the win notification URL. The SSP must call this URL when the auction is won, replacing ${AUCTION_PRICE} with the actual clearing price (CPM). PureGuard uses this to track daily spend and per-zone win caps.

Win Notice URL

GET https://pureguard.io/win.php?bid={bid_id}&price={clearing_price_cpm}&req={request_id}&zone={zone}&ssp={ssp_name}

Testing Your Integration

Test Bid Request (curl)

curl -X POST https://pureguard.io/bid.php \
  -H "Content-Type: application/json" \
  -d '{
    "id":"test-1",
    "imp":[{"id":"1","instl":1,"bidfloor":0.50,"ext":{"type":"pop"}}],
    "site":{"domain":"test.com"},
    "device":{"ua":"Mozilla/5.0 Chrome/131.0","geo":{"country":"US"},
              "ip":"1.2.3.4","devicetype":2},
    "at":1,"cur":["USD"]
  }'

# 200 = bid accepted (check response JSON)
# 204 = no bid (check RTB dashboard for reason)

Current SSP Status

SSP	Status	Notes
RTB exchanges	Live	Pop traffic, OpenRTB 2.5, win macro: `${AUCTION_PRICE}`
EvaDav	Code-ready	Endpoint configured, awaiting buying-side credentials from partner

Conversion Tracking (Postback)

PureGuard tracks conversions via server-to-server postback URLs. When a user converts on your offer, the smartlink or offer network fires a postback to PureGuard with the conversion details. This lets PureGuard attribute revenue to specific zones and power the zone quality engine.

How It Works

1 User clicks your ad → PureGuard's click.php filters and redirects clean traffic to your offer

2 User converts (sign up, purchase, etc.) on your offer/smartlink

3 Offer network fires postback to https://pureguard.io/postback.php?...

4 PureGuard logs the SALE event, attributes revenue to the zone, and updates your dashboard

Postback URL Parameters

Parameter	Required	Description
s2	Yes	Click ID / token. Must match the click ID passed in your campaign URL. This is how PureGuard links conversions back to the original click.
value	Optional	Payout amount (e.g. `2.50`). Used to calculate revenue per zone. Defaults to 0 if not provided.
s1	Optional	Zone ID. Used for per-zone revenue attribution. Should match the zone macro from your campaign URL.
network	Optional	Traffic source name (e.g. `HILLTOPADS`, `ROLLERADS`). Used for source-level revenue tracking.
wk	Recommended	Your workspace key. Found in your Connectors page. Enables tenant attribution — without it, conversions are logged but not linked to your account.
type	Optional	Event type. Use `ftd` for first-time deposit / sale events. Defaults to `conversion`.

Example Postback URL

Generic Format

https://pureguard.io/postback.php?s2={click_id}&value={payout}&s1={zone}&network=HILLTOPADS&wk=YOUR_WK

Network-Specific Macros

Each ad network uses different macro names. Use the correct macros for your network:

Network	Click ID (s2)	Zone (s1)	Payout (value)
premium pop networks	`{token}`	`{zone}`	`{payout}`
pop networks	`{clickId}`	`{zoneId}`	`{payout}`
pop networks	`[IMPRESSIONID]`	`[WEBSITEID]`	`{payout}`
ExoClick	`{click_id}`	`{zone_id}`	`{payout}`
push networks	`{click_id}`	`{zoneid}`	`{payout}`
Clickadu	`{clickid}`	`{zoneid}`	`{payout}`
AdMaven	`{clickId}`	`{subId}`	`{payout}`
pop networks	`{clickid}`	`{zoneid}`	`{payout}`
Adsterra	`{clickid}`	`{zoneid}`	`{payout}`
EvaDav	`{click_id}`	`{src_id}`	`{payout}`
pop networks	`[clickid]`	`[siteid]`	`{payout}`
push networks	`{clickid}`	`{zoneid}`	`{payout}`

Tip: You don't need to memorize these macros. Go to Connectors, edit your source, and the postback URL with correct macros is auto-generated and ready to copy.

Duplicate Protection

PureGuard automatically deduplicates conversions. If the same click ID (s2) fires a postback within 5 minutes, the duplicate is rejected. This prevents double-counting from network retries.

Response Format

Success

OK: Fired to HILLTOPADS | HILLTOPADS: HTTP 200. Sentinel Updated.

Duplicate

DUPLICATE: Conversion for token already recorded within 5 minutes.

Rate Limits

Rate limits are enforced per API key at the Nginx level. Exceeding the limit returns 429 Too Many Requests. The response includes a Retry-After header indicating when to retry.

Endpoint	Rate Limit	Burst	Notes
/api/v1/*	10 req/s	20	Per API key. Sufficient for most traffic volumes.
/click.php	30 req/s	60	Per IP. Direct click handler for redirect-based integration.
/bid.php	100 req/s	200	Per IP. OpenRTB endpoint handles high QPS from SSPs.

Enterprise customers can request custom rate limits. Contact support to increase limits for high-volume campaigns processing over 1M+ checks per day.

Error Codes

All error responses include a JSON body with an error field describing the issue.

Code	Status	Description	Resolution
200	OK	Request processed successfully	-
400	Bad Request	Missing or malformed request body. Required fields: `ip`, `ua`, `url`	Check your JSON payload for missing fields or syntax errors
401	Unauthorized	Missing or invalid API key in `X-API-Key` header	Verify your key in Settings. Regenerate if compromised.
403	Forbidden	Account suspended or plan does not include this endpoint	Contact support or upgrade your plan
429	Too Many Requests	Rate limit or monthly quota exceeded	Wait for `Retry-After` seconds, or upgrade for higher limits
500	Internal Error	Unexpected server error during processing	Retry the request. If persistent, check /api/v1/status

Error Response Format

401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": 401
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": 429,
  "retry_after": 2
}

Need help integrating?

Our team can help you set up PureGuard for your specific traffic stack.

Start Free Dashboard