Intelligence API

以版本化 API 取得真象樹整理的事件、來源、更新與更正通知。這是第三方串接的正式技術邊界；新聞原文、未授權圖片與內部審稿資料不會經由 API 提供。

目前狀態：技術預備完成

尚未開放自助註冊或付款；商用前仍需完成個別合約與法律審閱。

公開版本

契約版本

2026-07-30

回應格式

JSON

Project API key

增量同步

簽章 Webhook

有限資料授權

開始串接

1. 建立 customer project每個 project 綁定方案、test／live 環境及可使用的主題。
2. 安全保存 API keyKey 只會在發行時顯示一次；請放在伺服器端 secret manager，不要寫入前端程式。
3. 先同步，再追蹤更新先讀取 events 建立本地狀態，再使用 updates cursor 或 Webhook 持續同步。

端點

Method	Path	用途	認證
GET	/v1/topics	列出 project 已取得授權的主題與方案能力	API key
GET	/v1/events	分頁取得已發布事件	API key
GET	/v1/events/{id}	取得事件、來源與 provenance	API key
GET	/v1/updates	增量事件、更正與撤回通知	API key
GET	/v1/status	主題 freshness 與 coverage 狀態	公開
GET	/v1/openapi.json	OpenAPI 3.1 machine-readable contract	公開

cURL

curl "https://thetruetree.com/v1/events?topic=news&limit=20" \
  -H "Authorization: Bearer tt_test_REPLACE_WITH_YOUR_KEY"

TypeScript SDK

import { TrueTreeClient } from "./sdk/typescript";

const client = new TrueTreeClient({
  apiKey: process.env.TRUE_TREE_API_KEY!,
});

const page = await client.listEvents({ topic: "news", limit: 20 });
console.log(page.data.events);

錯誤、額度與恢復

錯誤使用 RFC 9457 類型的 application/problem+json，並回傳可提供支援人員追查的 request ID。429 可能代表短時間 rate limit 或月配額已用完；短時間限制會提供 Retry-After。

401: API key 無效、已撤銷、過期或 project 未啟用
403: 缺少 scope 或 topic entitlement
409: 主題已設定，但 production ingestion 尚未啟用
429: 每分鐘限制或月配額已達上限
503: API 或資料庫暫時無法提供服務；可安全重試 GET

Webhook 驗證

使用 endpoint signing secret 驗證 timestamp 與未解析的 request body，並拒絕時間差過大的通知。相同 delivery ID 可能因網路重試再次出現，接收端必須具備 idempotency。

X-True-Tree-Event: event.updated
X-True-Tree-Delivery: <delivery-uuid>
X-True-Tree-Signature: t=<unix-seconds>,v1=<hmac-sha256>

資料與授權邊界

API 提供事件 metadata、真象樹整理摘要、分類、關聯、更新時間及來源入口。客戶不得把來源連結或短摘錄當成已取得新聞全文、圖片或影音的再授權。

公開顯示、內部使用、再散布、AI／RAG 與歷史封存會採不同商業授權。更正、撤回或來源授權變更出現在 updates 與 Webhook 後，客戶端應在合約約定時間內同步處理。

目前條款是商用前準備草案，不構成已完成的個別授權。正式客戶啟用前，雙方仍需簽署資料用途、保存、 attribution、再散布、服務目標與下架義務。

開始串接

1. 建立 customer project每個 project 綁定方案、test／live 環境及可使用的主題。

2. 安全保存 API keyKey 只會在發行時顯示一次；請放在伺服器端 secret manager，不要寫入前端程式。

3. 先同步，再追蹤更新先讀取 events 建立本地狀態，再使用 updates cursor 或 Webhook 持續同步。

端點

Method	Path	用途	認證
GET	/v1/topics	列出 project 已取得授權的主題與方案能力	API key
GET	/v1/events	分頁取得已發布事件	API key
GET	/v1/events/{id}	取得事件、來源與 provenance	API key
GET	/v1/updates	增量事件、更正與撤回通知	API key
GET	/v1/status	主題 freshness 與 coverage 狀態	公開
GET	/v1/openapi.json	OpenAPI 3.1 machine-readable contract	公開

import { TrueTreeClient } from "./sdk/typescript"; const client = new TrueTreeClient({ apiKey: process.env.TRUE_TREE_API_KEY!, }); const page = await client.listEvents({ topic: "news", limit: 20 }); console.log(page.data.events);

錯誤、額度與恢復

401

API key 無效、已撤銷、過期或 project 未啟用

403

缺少 scope 或 topic entitlement

409

主題已設定，但 production ingestion 尚未啟用

429

每分鐘限制或月配額已達上限

503

API 或資料庫暫時無法提供服務；可安全重試 GET

Webhook 驗證

X-True-Tree-Event: event.updated X-True-Tree-Delivery: <delivery-uuid> X-True-Tree-Signature: t=<unix-seconds>,v1=<hmac-sha256>

資料與授權邊界

API 提供事件 metadata、真象樹整理摘要、分類、關聯、更新時間及來源入口。客戶不得把來源連結或短摘錄當成已取得新聞全文、圖片或影音的再授權。

目前條款是商用前準備草案，不構成已完成的個別授權。正式客戶啟用前，雙方仍需簽署資料用途、保存、 attribution、再散布、服務目標與下架義務。