跳到主要内容

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（已退役）。