示例

示例中的凭证都从环境变量读取（SITETRACE_TOKEN）；不要把工作区恢复密钥交给 AI 或写进脚本。

curl：结构化查询

curl -sS -X POST https://openstatx.com/api/v1/query \
  -H "authorization: Bearer $SITETRACE_TOKEN" -H 'content-type: application/json' \
  -d '{"site_ids":["'$SITE_ID'"],"dataset":"http_requests","metrics":["request_count"],"dimensions":["actor_class"],
       "time_range":{"start":"2026-09-29T00:00:00+09:30","end":"2026-09-30T00:00:00+09:30"},"timezone":"Australia/Adelaide"}'

TypeScript

const res = await fetch("https://openstatx.com/api/v1/sites/" + process.env.SITE_ID + "/overview?preset=last_7_days", {
  headers: { authorization: "Bearer " + process.env.SITETRACE_TOKEN },
});
const { data, meta } = await res.json();
console.log(data.totals.page_views, meta.quality_by_metric);

仓库中的 packages/client 提供类型化客户端。

Python

import os, requests
r = requests.get(f"https://openstatx.com/api/v1/sites/{os.environ['SITE_ID']}/automation",
                 params={"preset": "last_7_days", "view": "clients"},
                 headers={"authorization": f"Bearer {os.environ['SITETRACE_TOKEN']}"}, timeout=30)
r.raise_for_status()
for row in r.json()["data"]["rows"]:
    print(row)

服务端上报（签名）

import { createHmac, createHash, randomBytes } from "node:crypto";
const body = JSON.stringify({ v: 1, site_id: process.env.SITE_ID, batch_id: crypto.randomUUID(), events: [
  { event_id: "order-1001", type: "conversion", ts: Date.now(), order_id: "1001", revenue_minor: 1200, currency: "AUD" },
]});
const ts = Math.floor(Date.now() / 1000), nonce = randomBytes(16).toString("hex");
const sig = createHmac("sha256", process.env.SITETRACE_SIGNING_SECRET!).update(`${ts}.${nonce}.${createHash("sha256").update(body).digest("hex")}`).digest("hex");
await fetch("https://openstatx.com/api/v1/collect/server", { method: "POST", body, headers: {
  "content-type": "application/json", authorization: "Bearer " + process.env.SITETRACE_INGEST_TOKEN,
  "x-sitetrace-timestamp": String(ts), "x-sitetrace-nonce": nonce, "x-sitetrace-signature": "v1=" + sig } });

边缘适配器（Cloudflare Worker）

import { wrapWithAnalytics } from "@sitetrace/edge-adapter";
export default wrapWithAnalytics(originalHandler, { siteId: "st_...", endpoint: "https://openstatx.com", tokenEnv: "SITETRACE_INGEST_TOKEN", secretEnv: "SITETRACE_SIGNING_SECRET" });

适配器不改变原响应的状态码、头部、流式与缓存语义；上报失败只记录损失，不影响网站。

MCP 客户端

import { Client } from "@modelcontextprotocol/client";
// 见仓库 examples/ai/mcp-client.mjs：使用 Streamable HTTP 传输与 Bearer 凭证，调用 tools/list 与 get_report。