#Central Vantage API (xtnd-vantage-api)

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

#1. Overview

xtnd-vantage-api serves as the central data exchange and storage worker for the entire XTND Vantage platform. All edge gateways (api.sonar.vantage.xgi.io, api.radar.vantage.xgi.io) and client SDKs route their telemetry events to this service.

#2. API Endpoints

#2.1 Urgent Event Ingestion (POST /v1/events/urgent)

Ingests single high-priority P0_CRITICAL events that require immediate storage and potential alert routing.

• Method: POST
• Path: /v1/events/urgent
• Headers:
  • Content-Type: application/json
  • X-Vantage-Client: xtnd-vantage-sdk/1.0 (optional)
• Request Body:

  {
    "id": "c6a1b2d3-e4f5-4678-8901-abcdef123456",
    "type": "ai:quota:exhausted",
    "source": "api.sonar.vantage.xgi.io",
    "priority": "P0_CRITICAL",
    "timestamp": 1757059200000,
    "payload": {
      "provider": "anthropic",
      "remainingCreditsUsd": 0.00,
      "monthlyLimitUsd": 2000.00,
      "isCritical": true
    }
  }

• Processing Logic:
  1. Writes to Cloudflare KV: env.VANTAGE_KV.put("event:urgent:${event.id}", JSON.stringify(event), { expirationTtl: 604800 }) (7-day TTL).
  2. Emits an urgent counter to env.VANTAGE_ANALYTICS.writeDataPoint().
  3. Returns HTTP 200 OK immediately.
• Response:

  {
    "status": "acknowledged",
    "id": "c6a1b2d3-e4f5-4678-8901-abcdef123456"
  }

#2.2 Batch Event Ingestion (POST /v1/events/batch)

Ingests arrays of non-urgent P1_HIGH, P2_NORMAL, and P3_DEFERRED events flushed periodically by clients and edge gateways.

• Method: POST
• Path: /v1/events/batch
• Headers:
  • Content-Type: application/json
  • X-Module-Source: sonar | radar | sentinel (optional)
• Request Body:

  {
    "events": [
      {
        "id": "1111-2222-3333-4444",
        "type": "page:init",
        "source": "laogpt.com",
        "priority": "P2_NORMAL",
        "timestamp": 1757059200000,
        "payload": { "route": "/chat", "viewport": "1920x1080" }
      },
      {
        "id": "5555-6666-7777-8888",
        "type": "ai:openai:inference",
        "source": "api.sonar.vantage.xgi.io",
        "priority": "P2_NORMAL",
        "timestamp": 1757059201000,
        "payload": { "model": "gpt-4o", "totalCostUsd": 0.0045 }
      }
    ]
  }

• Processing Logic:
  • Leverages ctx.waitUntil() to asynchronously iterate through all events and write columnar metrics to env.VANTAGE_ANALYTICS.
  • Prevents worker memory saturation while providing sub-5ms HTTP responses.
• Response:

  {
    "status": "received",
    "count": 2
  }

#2.3 Health & System Info (GET /v1/health or GET /)

• Method: GET
• Response:

  {
    "service": "XTND Vantage Central Exchange",
    "domain": "api.vantage.xgi.io",
    "status": "OPERATIONAL",
    "region": "sin01",
    "timestamp": "2026-09-05T07:45:00.000Z"
  }

#2.4 The websites XRADAR reports from (/v1/web/*, since 1.2.0)

For the same readers as the dashboard summary: events.read at Vantage, or an Argus licence. Argus's Websites and Replay read these.

The stats route answers with:

• totals: visitors, sessions, page views and clicks;
• counts by day (in the caller's time zone), by page and by language;
• named events, and referrers by host;
• devices and browsers;
• Core Web Vitals: the 75th percentile and median, each with the rating XRADAR gave that sample, and how all samples rated;
• engagement: median time, engaged time and read;
• errors.

Rows in the lake keep their place. When a payload goes to the lake (over 8 KB), its row keeps XRADAR's app, visitor, session, view and seq beside the pointer. Rows stored before 1.2.0 are found by time and read from the lake.

Schema. Migration 0002_vantage_web_sessions.sql adds a generated session column (VIRTUAL, the kind ALTER TABLE can add in D1) with an index, and an index on (source, timestamp).

#3. Storage Bindings Configuration

In wrangler.jsonc:

{
  "name": "xtnd-vantage-api",
  "main": "src/index.ts",
  "compatibility_date": "2025-04-01",
  "compatibility_flags": ["nodejs_compat"],
  "routes": [
    { "pattern": "api.vantage.xgi.io", "custom_domain": true }
  ],
  "vars": {
    "ENVIRONMENT": "production"
  },
  "observability": { "enabled": true }
}