VANTAGE
Documentation

Radar Web Analytics API (xtnd-radar-api)

Repository: XTND-DYNAMICS/xtnd-radar-api
Production Route: https://api.radar.vantage.xgi.io
Runtime: Cloudflare Worker (nodejs_compat)

1. Overview

xtnd-radar-api is the web telemetry gateway for the XTND ecosystem. It takes the events of the sites on its list (ALLOWED_ORIGINS): LaoGPT (laogpt.com, www.laogpt.com), ThaiGPT+ (thaigpt.xgi.io) and the Evergreen AI website (evergreenai.la, www.evergreenai.la, www.everlao.com). The Evergreen AI site reports with XRADAR (radar-sdk.md).

  • Who may send. Only those origins. The site an event is filed under is taken from the request's Origin (without www.), never from the event. Any other origin gets 403 origin not allowed, and XRADAR stops sending on a 403.
  • Stored, then answered. The gateway hands events to central through its private Ingest binding and answers 2xx only once they are stored. Otherwise it answers 503 with Retry-After, and the sender keeps the events.

2. API Endpoints

2.1 Ingest Web Telemetry (POST /v1/events/web)

Receives single events or batched event arrays from the RadarStorageManager or browser clients.

  • Method: POST
  • Path: /v1/events/web
  • Headers:
    • any Content-Type; the body is read as JSON. XRADAR sends text/plain, a simple request with no preflight, which a beacon can carry across origins.
    • Origin: must be on ALLOWED_ORIGINS.
  • Request Body (Single Event):
    {
  "id": "78a9b0c1-d2e3-4f56-7890-123456789abc",
  "type": "page:init",
  "source": "laogpt.com",
  "priority": "P2_NORMAL",
  "timestamp": 1757059200000,
  "payload": {
    "route": "/chat",
    "referrer": "https://google.com",
    "viewport": "1440x900",
    "appName": "LaoGPT Web"
  }
}
  • Request Body (Batch Array):
    {
  "events": [
    {
      "id": "...",
      "type": "user:prompt_submit",
      "priority": "P2_NORMAL",
      "payload": { "length": 42 }
    },
    {
      "id": "...",
      "type": "web_vitals",
      "priority": "P2_NORMAL",
      "payload": { "name": "LCP", "value": 1240, "rating": "good" }
    }
  ]
}
  • Forwarding Pipeline:
    • Automatically wraps individual events into standard batches.
    • Asynchronously dispatches the batch to env.CENTRAL_VANTAGE_API/v1/events/batch inside ctx.waitUntil().
    • Responds immediately with HTTP 200 OK.
  • Response:
    {
  "status": "received",
  "gateway": "api.radar.vantage.xgi.io"
}

2.2 Health Status (GET /v1/health or GET /)

  • Method: GET
  • Response:
    {
  "service": "XTND Vantage Radar Web Analytics Gateway",
  "domain": "api.radar.vantage.xgi.io",
  "status": "OPERATIONAL",
  "timestamp": "2026-09-05T07:45:00.000Z"
}

3. Configuration & Deployment

In wrangler.jsonc (merging to main deploys):

{
  "name": "xtnd-radar-api",
  "main": "src/index.ts",
  "workers_dev": false,
  "routes": [{ "pattern": "api.radar.vantage.xgi.io", "custom_domain": true }],
  // central's intake is private: xtnd-vantage-api's Ingest entrypoint, reached only through this binding
  "services": [{ "binding": "CENTRAL", "service": "xtnd-vantage-api", "entrypoint": "Ingest" }],
  "vars": {
    "ENVIRONMENT": "production",
    // the only pages that may send; the site each event is filed under comes from here
    "ALLOWED_ORIGINS": "https://laogpt.com,https://www.laogpt.com,https://thaigpt.xgi.io,https://evergreenai.la,https://www.evergreenai.la,https://www.everlao.com"
  },
  "observability": { "enabled": true }
}

A new site is added to ALLOWED_ORIGINS before its events can arrive.