API 文档导读
API 文档与接入指南的分工、按版本与上下文的组织方式、参数表的读法，以及当前的完成度。
API 文档回答的是精确含义问题：这个字段是什么类型、必填还是可选、边界在哪、出错返回什么。它不教你怎么接入——那是接入指南的事。
本页说明两者的分界、这个板块的组织方式，以及现在能查到什么、查不到时去哪。
与接入指南的分工
同一件事在两处出现时，接入指南讲流程，本板块讲字段，不重复描述同一层信息。
组织方式
分四层，自上而下逐层收窄：
v1 的三个上下文与受众一一对应：
| 上下文 | 受众 | 包含什么 | 状态 |
|---|---|---|---|
| auth 上下文 | auth | 用户信息读取、身份断言校验 | 编写中 |
| oauth 上下文 | oauth | 令牌、撤销、自省、已授权应用管理、同意页内部端点 | 编写中 |
| account 上下文 | account | 账户资料 | 编写中 |
参数表的读法
本板块的参数表统一按下面的约定书写：
| 列 | 含义 |
|---|---|
| 名称 | 参数名，区分大小写 |
| 类型 | string / integer / boolean / array / object |
| 必填 | 「是」表示缺失会直接报错；「否」表示省略后有默认行为 |
| 约束 | 长度、取值集合、格式要求；写「无」表示不做额外限制 |
| 示例 | 示意值，不是契约 |
三条读表规则：
- 必填不等于够用：参数齐了但取值不合法，仍然是参数错误，错误码会指出是哪一个；
- 约束是硬边界：超出约束的请求不会被「尽力处理」，而是直接拒绝；
- 未列出的字段视为不存在：不要依赖响应里没写进文档的字段，它们随时可能消失。
当前完成度
通用约定与端点总表已就绪，逐上下文的字段文档正在补齐。未完成的页面会明确标注「编写中」，并列出计划覆盖的接口。
查不到某个字段时，按这个顺序退让：
多数疑问在这三页就能解决，剩下的才是本板块要补的内容。