Documentation › REST API

REST API reference

Full API access is available on Pro and Enterprise plans. Authenticate with your API key in the Authorization header.

Authentication

All API requests require your API key in the Authorization header:

Authorization: Bearer GG-YOUR-API-KEY

API keys are managed from the API keys tab in your dashboard. You can create multiple keys, label them by use case, and revoke them individually. Revocation is immediate.

⚠ Keep your API key secret. Never expose it in client-side JavaScript or public repositories. Rotate it immediately if compromised.

Guard endpoint

The guard endpoint is the core decision API called by the PHP client. It validates the session and returns an allow/block decision. Available on all plans.

POST /api/check

Evaluate a session and return an allow/block decision.

ParameterTypeRequiredDescription
api_keystringrequiredYour GhostGuard API key
sidstringrequiredSession ID from the GhostGuard session cookie
ipstringoptionalVisitor IP address for ban-list check
uastringoptionalVisitor user-agent string
hoststringoptionalCustomer domain for domain validation
urlstringoptionalCurrent page URL for logging
// Response
{
  "ok": true,
  "decision": "allow", // "allow" or "block"
  "blocked": false,
  "score": 91, // 0-100, higher = more human
  "verdict": "human", // "human", "suspicious", or "bot"
  "reason": "allowed"
}

Account stats

GET /api/stats

Returns today's session counts, bot counts, mail stats, and monthly usage.

{
  "sessions_today": 1840,
  "bots_today": 143,
  "suspicious_today": 87,
  "avg_score": 72.4,
  "mail_today": 24,
  "mail_blocked_today": 3,
  "usage": { "web_sessions": 48203, "bots_blocked": 3821 },
  "trial_days": null,
  "status": "active"
}

Live session feed

GET /api/feed

Returns recent sessions for your account. Poll every 5 seconds for a live feed.

ParameterDefaultDescription
limit60Number of sessions to return (max 100)

Domains

GET /api/domains

List all registered domains with monthly session and bot counts.

POST /api/domain/add

Register a new domain. Body: {"domain": "example.com"}

POST /api/domain/toggle

Enable or disable a domain. Body: {"id": 123}

POST /api/domain/delete

Permanently delete a domain and all associated sessions. Body: {"id": 123}

Ban management

GET /api/bans

List all bans for your account. Filter by type with ?type=ip|session|email

POST /api/ban

Add a manual ban. Body: {"type": "ip", "value": "1.2.3.4", "reason": "Manual ban"}

POST /api/unban

Remove a ban by ID. Body: {"id": 456}

API key management

GET /api/keys

List all API keys for your account, including last-used timestamps.

POST /api/key/create

Create a new API key. Body: {"label": "Production"}

POST /api/key/revoke

Revoke a key immediately. Body: {"id": 789}

Error responses

HTTP statusMeaning
400Bad request — missing or invalid parameters
401Unauthorized — missing or invalid API key
403Forbidden — API key valid but domain not registered or account suspended
429Rate limited — monthly session quota exceeded for your plan
500Server error — GhostGuard internal error, fail-open applies
// Error response structure
{ "ok": false, "error": "missing_api_key" }