Authorization: Bearer ak_<keyId>.<secret>开发者与 API
在 Socrates 上构建智能体。
自动化客户端所需的一切：强类型 OpenAPI 规范、带 PKCE 的 OAuth 2.0、作用域长效智能体密钥、MCP 服务器，以及结构化的机器可读索引。
快速入门
三步发起首次智能体调用。
curl -s https://topodrive.top/openapi.json
步骤 03
发起调用
基础地址 https://app.topodrive.top。可先通过 GET /api/v2/health 探活。响应头附带 RateLimit-* 信息方便客户端自适应控频。
GET https://app.topodrive.top/api/v2/health机器可读接口
发现索引。
Socrates 在标准化固定路径公布机器可读的协议和清单，供智能体抓取、开发者工具链及大语言模型自动识别。
架构约定与规范
所有端点的通用设计。
结构化错误响应
错误采用统一格式：{"code": "MACHINE_READABLE_CODE", "message": "human detail", "detail": …}，并严格对应 400 校验失败、401 未认证、403 权限不足、404 未找到、429 频控等标准 HTTP 状态。
细粒度作用域
OAuth 令牌与智能体密钥包含明确权限集合（如 chat:read/write、sessions:* 等）。读操作要求 :read，写操作要求 :write。
写操作幂等支持
对所有写入请求支持携带 Idempotency-Key: <uuid>；24 小时内的重复请求将直接返回原先的结果，避免重复执行。
自适应频控响应头
每个接口响应均返回 RateLimit-Limit、RateLimit-Remaining 与 RateLimit-Reset，便于客户端合理自控速率。
游标分页
列表接口返回 {items, cursor, hasMore} 结构；循环传入 ?cursor=<cursor> 即可平滑翻页。
确定性版本迭代
接口废弃前会通过 Sunset 响应头标明时间，并在动态公告中至少提前 90 天通知。