TraceHubTraceHub
Documentation

TraceHub Developer Docs

Our API ingests request metadata and returns an allow/decline decision based on settings you configure in the dashboard.

Quickstart

Protect in minutes

Get an API key, add a page in the dashboard, then send a request log.

1. Get an API Key
From Settings → API Keys in your dashboard.
headers.txt
1Authorization: Bearer YOUR_API_KEY
2. Add a Page in Dashboard
We do not create pages via API. Use Dashboard → Pages.
Pages are your protected properties (e.g., domains/sections). All API decisions reference apageId you create in the dashboard.
3. Send a Request Log
Get an allow/block decision in real time.
curl
curl.sh
1curl -X POST https://api.tracehub.xyz/v1/requests -H "Authorization: Bearer $TRACEHUB_API_KEY" -H "Content-Type: application/json" -d '{ 2 "pageId": "PAGE_ID", 3 "ip": "203.0.113.42", 4 "userAgent": "Mozilla/5.0 ..." 5 }'

Response (example)

response.json
1{ 2 "decision": "allow", // or "decline" 3 "reasons": ["known-good-country", "normal-velocity"], 4 "requestId": "req_01HZX..." 5}

Authentication

Include your API key as a Bearer token. We infer country from the IP.

headers.txt
1Authorization: Bearer YOUR_API_KEY

Base URL

EnvironmentBase URL
Public APIhttps://api.tracehub.xyz

API Reference · Decision Ingest

Our API only accepts incoming requests. Send pageId, ip, and userAgent. We infer country from the IP.

Endpoint

endpoint.txt
1POST https://api.tracehub.xyz/v1/requests

Request Body

request.json
1{ 2 "pageId": "PAGE_ID", 3 "ip": "203.0.113.42", 4 "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ..." 5}

curl

curl.sh
1curl -X POST https://api.tracehub.xyz/v1/requests -H "Authorization: Bearer $TRACEHUB_API_KEY" -H "Content-Type: application/json" -d '{ 2 "pageId": "PAGE_ID", 3 "ip": "203.0.113.42", 4 "userAgent": "Mozilla/5.0 ..." 5 }'

Response

response.json
1{ 2 "decision": "allow", // or "decline" 3 "reasons": ["known-good-country", "normal-velocity"], 4 "requestId": "req_01HZX..." 5}
Code Examples

Code Examples

Use these snippets to call the decision API. If the decision isdecline, doSomething() such as redirecting, returning 404, or responding with fake data.

PHP (cURL)
Server-side allow/decline handling.
example.php
1<?php 2$apiKey = getenv('TRACEHUB_API_KEY'); 3$payload = [ 4 'pageId' => 'PAGE_ID', 5 'ip' => $_SERVER['REMOTE_ADDR'] ?? '0.0.0.0', 6 'userAgent' => $_SERVER['HTTP_USER_AGENT'] ?? '', 7]; 8 9$ch = curl_init('https://api.tracehub.xyz/v1/requests'); 10curl_setopt($ch, CURLOPT_HTTPHEADER, [ 11 'Authorization: Bearer ' . $apiKey, 12 'Content-Type: application/json' 13]); 14curl_setopt($ch, CURLOPT_POST, true); 15curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload)); 16curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 17 18$response = curl_exec($ch); 19if ($response === false) { 20 http_response_code(500); 21 exit('TraceHub error'); 22} 23curl_close($ch); 24 25$data = json_decode($response, true); 26$decision = $data['decision'] ?? 'allow'; 27 28if ($decision === 'decline') { 29 // doSomething(): redirect, 404, or fake data 30 // header('Location: /blocked'); exit; // redirect 31 // http_response_code(404); exit; // 404 32 // echo json_encode(['items' => []]); exit; // fake data 33} 34 35// continue normally for "allow" ...
Next.js middleware.ts
App Router example with conditional control.
middleware.ts
1// middleware.ts (at project root) 2import { NextResponse, NextRequest } from 'next/server'; 3 4export async function middleware(req: NextRequest) { 5 const ip = req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || '0.0.0.0'; 6 const userAgent = req.headers.get('user-agent') || ''; 7 8 const res = await fetch('https://api.tracehub.xyz/v1/requests', { 9 method: 'POST', 10 headers: { 11 Authorization: 'Bearer ' + (process.env.TRACEHUB_API_KEY ?? ''), 12 'Content-Type': 'application/json', 13 }, 14 body: JSON.stringify({ pageId: 'PAGE_ID', ip, userAgent }), 15 }); 16 17 if (!res.ok) return NextResponse.next(); 18 const data = await res.json(); 19 20 if (data.decision === 'decline') { 21 // doSomething(): redirect, 404, or fake data 22 // return NextResponse.redirect(new URL('/blocked', req.url)); 23 return new NextResponse(null, { status: 404 }); 24 } 25 26 return NextResponse.next(); 27} 28 29export const config = { 30 // protect all routes except Next internals & static assets 31 matcher: ['/((?!_next|favicon.ico).*)'], 32};