跳至主要内容

API 文件

API 文件是渲染於 /api 的 OpenAPI 文件。它是路由、參數、請求內容、 回應 schema 與狀態碼的唯一出處。本頁說明文件假設的慣例。

文件在哪​

  • 渲染版：/api
  • 機器可讀：GET /v2/openapi.json（不需要金鑰）
  • 資料集欄位定義：GET /v2/schemas
  • 合約檔：repo 內的 contracts/openapi/v2.yaml

GET /v2/schemas 回傳每個資料集的欄位、共同欄位（symbol、 instrument_id、ts、trading_day、seq、flags）與 flag 位元。 served 表示 /v2/data 目前能不能回答該資料集。served: false 的 schema 是合約定義，不是資料承諾；商品回應的 datasets 才是它實際有的資料。

Base URL 與認證​

https://data.cyberun.cloud
Authorization: Bearer vmk_...

除了 GET /v2/openapi.json，每個 /v2 路由都需要金鑰。目錄需要任何有效金鑰； 資料、K 線、匯出與即時需要 API 金鑰說明的權限。

慣例​

  • 時間是 RFC 3339 UTC；請求的時間點必須帶時區或 Z。
  • 交易日是 YYYY-MM-DD，依商品的交易所日曆。
  • 小數預設是 JSON 字串；numbers=float 改回數字。
  • 分頁用 cursor 與 next_cursor；cursor 屬於它的查詢。
  • 目錄版本：每個回應帶 catalog_version；傳回可固定可重現的結果，直到 版本退役。
  • 錯誤是 application/problem+json；見錯誤。
  • 變更只做加法：新路由、選填參數、欄位與列舉值；用戶端要忽略不認得的 內容。

路由群組​

群組路由用途
目錄/v2/catalog/venues、/products、/instruments、/instruments/{symbol}、/datasets、/calendar什麼存在、什麼時候交易
資料GET /v2/data/{dataset}分頁原始資料列
K 線GET /v2/bars伺服器端 K 線，含連續合約
匯出POST /v2/exports、GET /v2/exports/{id}、GET /v2/exports/{id}/files/{file_index}批次檔案
串流GET /v2/streamWebSocket 資料列與 K 線
MetaGET /v2/openapi.json、GET /v2/schemas、POST /v2/mcp合約與 agent 工具

每個路由的參數、預設值與回應欄位在 /api。跨路由的操作限制在 限制。

管理​

Principal、金鑰與使用政策管理仍使用 /v1，沒有 OpenAPI 文件。見 管理。

版本​

公開合約以 /v2 路徑與 OpenAPI 的 info.version 標示版本。加法變更不會換 路徑。會破壞既有請求的變更不會默默發生；那會是新的路徑。

舊的 /v1 資料 API 已退役；見 v1（已退役）。