驰陌智能体开放 API

让用户自己的 AI 智能体读取本人在驰陌的运动与健康数据

English

这是什么

驰陌 App 支持把你本人的运动与健康数据，通过 API 提供给你自己搭建或托管的智能体（AI Agent）。

典型用法：让智能体每天读一次你的睡眠与恢复状态，生成训练建议；或把跑步记录汇总进你自己的笔记库。

三条硬性约定

以只读为主：绝大多数接口是 GET。仅 8 条写操作（跑步/路线收藏、关注）会改动你自己的数据，且它们需要写权限 —— 写权限默认不授予，要你在“智能体接入”里显式勾选才会生效。
仅本人：所有接口只返回你本人的数据（例外：社区动态、路线榜单等本就公开的信息）。
量纲显式：数值一律形如 {"value": 7.2, "unit": "h"}，不会给裸数字让你猜单位。

智能体不能代你跑步，因此本 API 不开放任何写入运动数据的接口 —— 否则排行榜、挑战与积分都可以被脚本刷穿。

一、开启与获取密钥

打开驰陌 App →「我的」→「帮助」菜单组 →「智能体接入」。
该功能默认关闭，需要你主动开启；开启时会弹出授权说明，需你确认。
点击生成密钥，复制保存。密钥只在生成时展示一次，之后无法再次查看。
密钥永久有效，但你可以随时重置或关闭接入。重置后旧密钥立即失效。

密钥等同于你的数据读取权限。请勿写入代码仓库、截图或分享给他人。若怀疑泄露，请立即在 App 内重置。

二、认证

在每个请求的头部携带密钥：

curl -H "X-API-Key: sk_sm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://www.8keya.com/api/v1/agent/capabilities

三、快速上手

建议第一步先调 /agent/capabilities：它会告诉你这把密钥能访问哪些接口、有哪些权限、限流额度是多少。

然后一次调用拿到当天全貌：

curl -H "X-API-Key: sk_sm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://www.8keya.com/api/v1/agent/overview

四、权限范围（scope）

生成密钥时默认授予全部只读权限；写权限（write:*）默认不授予，需你显式勾选。下列每一项都是一类数据的权限：

scope	说明
read:profile	个人资料、累计统计、跑境/骑境
read:runs	跑步记录列表、详情、均值、收藏夹
read:stats	周/月/年汇总统计
read:routes	路线列表、详情、榜单、附近
read:social	好友与关注关系
read:challenges	挑战列表、排名、详情、对比
read:health	健康数据点、日统计、历史、恢复、心电图
read:devices	已绑定设备与状态
read:points	积分余额、流水、商品
read:content	社区动态、帖子、评论（公开内容）
read:notifications	本人通知
read:ai	已生成的 AI 分析结果（只读）
read:system	天气、逆地理编码、版本、公开配置
read:agent	智能体聚合端点
write:bookmarks	跑步记录收藏 / 取消收藏（写入·默认不授予）
write:favorites	跑步与路线收藏 / 取消（写入·默认不授予）
write:follow	关注 / 取消关注用户（写入·默认不授予）

五、接口总览

共 60 个接口，其中 8 个为写操作（需 write:* 权限，默认不授予），其余为只读 GET。标注「仅限本人 / 仅限参与方」的接口会校验归属，越权访问返回 403。

agent智能体聚合

接口	说明
GET /agent/capabilities	自描述：本 Key 的权限范围、可用端点全集、量纲约定、限流额度智能体靠它自举，无需猜测。
GET /agent/health-summary	近 N 天健康汇总（不给原始时序点） ?days=1-30（默认 7）。原始点请用 /health/* 按窗口取。参数：`days` 可选（字符串）
GET /agent/overview	概览：今日活动 + 最近一次跑步 + 恢复状态 + 跑境一次调用替代原来 5~6 次。
GET /agent/recent-runs	最近跑步摘要（含量纲与每次配速） ?limit=1-200（默认 5）&page。参数：`limit` 可选（字符串） · `page` 可选（字符串）
GET /agent/today	当日全部身体指标（步数/距离/热量/睡眠/VO2max/ECG 数） ?date=YYYY-MM-DD 可查指定日，默认服务器当日。参数：`date` 可选（日期，默认 None）
GET /agent/weekly-report	本周与上周跑量/时长/次数/配速对比 ?date= 指定基准日，默认本周。参数：`date` 可选（日期，默认 None）

profile个人资料与等级

接口	说明
GET /user/paojing	跑境（跑步等级体系）当前境界、进度、徽章。
GET /user/profile	本人资料含昵称、头像、身体参数、VIP 等级等。
GET /user/qijing	骑境（骑行等级体系）
GET /user/stats/heats	运动热力图按日期聚合的运动强度。
GET /users/{id}/stats	累计统计（仅限本人） ⚠️ 路径参数必须是本人 users.id，否则 403。

runs跑步记录

接口	说明
GET /runs	跑步记录列表（分页） ?page&page_size（上限 200）。参数：`page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 10）
GET /runs/{id}	跑步详情（仅限本人记录）他人的 run 返回 401。
GET /runs/{id}/bookmark	收藏一条跑步记录（写入）重复收藏返回业务错误；带 Idempotency-Key 时重放返回首响。
GET /runs/{id}/bookmark	取消收藏一条跑步记录（写入）未收藏时调用不报错。
GET /runs/{id}/favorite	把跑步记录加入收藏（写入）与 bookmark 是两套独立列表，App 内分别展示。
GET /runs/{id}/favorite	把跑步记录移出收藏（写入）
GET /runs/averages	跑步均值（配速/距离/时长/步频）
GET /runs/bookmarks/list	跑步收藏夹参数：`sport_type` 可选（字符串，默认 None）

stats汇总统计

接口	说明
GET /stats	周/月/年汇总统计 ?period=week\|month\|year\|total&sport_type=all\|run\|cycle&date= 参数：`sport_type` 可选（字符串，默认 all） · `period` 可选（字符串，默认 week） · `date` 可选（字符串，默认 None）

routes路线

接口	说明
GET /routes	路线列表
GET /routes/{id}	路线详情
GET /routes/{id}/favorite	收藏一条路线（写入）
GET /routes/{id}/favorite	取消收藏一条路线（写入）
GET /routes/{id}/leaderboard	路线榜单（公开）参数：`page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 20） · `sort_by` 可选（字符串，默认 None） · `sport_type` 可选（字符串，默认 None）
GET /routes/favorites	收藏的路线参数：`page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 10）
GET /routes/nearby	附近路线（公开） ?lat&lng&radius（米）&limit。参数：`lat` 必填（数值） · `lng` 必填（数值） · `radius` 可选（数值，默认 5000） · `limit` 可选（整数，默认 20）

social好友与关注

接口	说明
GET /friends	好友列表参数：`page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 20）
GET /friends/requests/pending	待处理的好友请求参数：`page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 20）
GET /users/{id}/follow	关注一个用户（写入） :id 是被关注者的 users.id；不能关注自己。操作者永远是 Key 所属用户本人。
GET /users/{id}/follow	取消关注一个用户（写入）
GET /users/followers	我的粉丝列表参数：`page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 20）
GET /users/followings	我的关注列表参数：`page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 20）

challenges挑战

接口	说明
GET /challenges	挑战列表 ?status&page&page_size。参数：`status` 可选（字符串） · `page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 10）
GET /challenges/{id}	挑战详情（仅限参与方）非参与方 403。
GET /challenges/{id}/comparison	挑战对比报告（仅限参与方）非参与方 403。
GET /challenges/ranking	挑战榜排名（公开） ?type=challenger\|defender&limit。参数：`type` 可选（字符串，默认 challenger） · `limit` 可选（整数，默认 20）

health健康数据

接口	说明
GET /health/daily-stats	每日健康统计 ⚠️ from/to（YYYY-MM-DD）必填，跨度 ≤30 天。参数：`from` 必填（日期） · `to` 必填（日期）
GET /health/data-points	健康数据点（心率/血压/血氧/压力/侵入式） ⚠️ 必须显式给 from/to，单次跨度 ≤30 天。参数：`type` 必填（字符串） · `from` 必填（整数） · `to` 可选（整数，省略则无上限） · `page` 可选（整数，默认 1） · `size` 可选（整数，默认 100）
GET /health/ecg	心电图记录 ⚠️ from/to 必填，跨度 ≤30 天。参数：`from` 必填（整数） · `to` 可选（整数，省略则无上限） · `page` 可选（整数，默认 1） · `size` 可选（整数，默认 20）
GET /health/history	健康历史（按类型/日期） ⚠️ ?type 必填；start_date+end_date 跨度 ≤30 天。参数：`type` 必填（字符串） · `start_date` 必填（字符串） · `end_date` 必填（字符串） · `date` 必填（日期）
GET /health/recovery	运动恢复聚合（恢复时间/训练负荷/身体状态/VO2max/本周跑量）服务端固定窗口聚合，无需时间参数。

devices设备

接口	说明
GET /devices	已绑定设备（型号/电量/最后同步时间）

points积分

接口	说明
GET /points/balance	积分与 Token 余额
GET /points/products	可兑换商品列表
GET /points/transactions	积分流水参数：`page` 可选（字符串，默认 1） · `page_size` 可选（字符串，默认 20） · `type` 可选（字符串，默认 0）

content社区内容

接口	说明
GET /feed	社区动态流（公开内容）参数：`cursor` 可选（字符串，默认 None） · `limit` 可选（整数，默认 10） · `from` 可选（字符串） · `to` 可选（字符串）
GET /feed/{id}/track	动态关联的运动轨迹（公开内容）
GET /posts	帖子列表（公开内容）参数：`page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 10）
GET /posts/{id}	帖子详情（公开内容）
GET /posts/{id}/comments	帖子评论（公开内容）参数：`page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 10）

notifications通知

接口	说明
GET /notifications	本人通知列表参数：`page` 可选（整数，默认 1） · `page_size` 可选（整数，默认 20）
GET /notifications/unread/count	未读通知数

aiAI 结果

接口	说明
GET /ai/analyses/{run_id}	已生成的跑步分析结果（只读，不触发新调用）仅返回本人分析的缓存；无结果 404，他人分析 403。
GET /ai/daily-quote	每日一言参数：`city` 可选（字符串） · `locale` 可选（字符串）
GET /ai/features	AI 功能清单

system系统公共能力

接口	说明
GET /app/version	最新 App 版本（公开）参数：`current` 可选（整数，默认 0） · `platform` 可选（字符串，默认 android）
GET /geocode/reverse	逆地理编码（公开） ?lat&lng。参数：`location` 必填（字符串）
GET /system/config/{key}	公开系统配置项（公开）
GET /weather	天气（公开）参数：`city` 必填（字符串） · `lat` 必填（数值） · `lng` 必填（数值） · `locale` 可选（字符串）

六、量纲约定

所有数值字段都是带量纲对象。单位与含义如下：

field	unit
distance	m
duration	s
pace	s/km
cadence_run / cadence_cycle	spm / rpm
steps	count
calories	kcal
sleep	h
heart_rate	bpm
blood_oxygen	%
body_temp	°C
vo2max	ml/kg/min

心率的单位是 bpm；血氧为 %；体温为 °C。另有两个 无量纲 的手环原生指数（训练负荷、身体状态），取值 0-10，含义见 App「运动恢复」卡片，请勿当作物量计算。

七、错误处理

失败时返回真实 HTTP 状态码（不是把错误藏在 200 里），响应体统一为 {code, message}：

HTTP	说明
400	参数不合法
401	缺少 / 无效 / 已重置的 API Key
403	权限不足，或试图访问他人数据
404	资源不存在或不属于本人
429	超出限流额度（见 Retry-After）

八、限流

默认每把密钥每分钟 60 次、每天 5000 次。超限返回 429，并带 Retry-After 头。

九、时间与时区

时间戳为 UTC 秒或 RFC3339 格式，同时附带 local_date。所有时序接口必须显式给出时间范围，单次跨度不超过 30 天。

十、隐私与免责

数据由驰陌服务器直接返回给你指定的调用方，驰陌不会把数据另外提供给第三方。
健康类数据来自消费级穿戴设备，仅供参考，不构成医疗建议，不得用于诊断或治疗决策。
你可以随时在 App 内关闭接入或重置密钥，重置后原密钥立即失效。

所有返回健康数据的接口都会在响应顶层附带 disclaimer 字段（中英并列）。请在你的智能体输出中保留该声明，不要把它当成可以省略的装饰字段。

十一、MCP 接入（不用写代码）

如果你使用的客户端支持 MCP，可以不写任何 HTTP 代码 —— 把驰陌的 MCP 服务地址填进去，客户端会自动发现可用工具。详见 MCP 接入。

机器可读规格

本项目同时提供 OpenAPI 3.1 规格，可直接导入支持 function calling 的智能体平台：

agent-openapi.yaml

驰陌（StrideMoor）

驰陌 智能体开放 API