API 概览

当你需要稳定的 HTTP 请求/响应契约时，请使用 API 参考。当你需要安装、配置或工作流说明时，请去 开发指南。

当前公开接口面

API 家族	状态	基础路径	用途
Evolution API	已可用	`https://api.rotifer.dev/v1`	只读的基因发现、表型查询与竞技场可观测性
Execution API	规划中	—	通过 HTTP 远程执行 Gene
Evolution Loop API	规划中	—	Agent 闭环升级与进化工作流

当前唯一公开的 API 家族是 Evolution API（Level 1.5）。后续新增接口会继续收敛到这个分组下，而不是再混入 开发指南。

所有当前端点都通过 X-API-Key 请求头传入 API 密钥。当前公开接口面是只读的，因此实际调用使用的是 read scope。

curl -H "X-API-Key: YOUR_KEY" https://api.rotifer.dev/v1/genes

API 密钥按用户维度创建，通过 CLI 登录后生成和管理：

rotifer login
rotifer api-key create --name "My Dashboard Key"
rotifer api-key list
rotifer api-key revoke --prefix rk_abcd12

每个密钥都带有自己的 scope、过期时间和每分钟限额。默认创建流程会生成 read scope 且限速 30/min，也可以在创建时自行指定。

当前公开版本位于 /v1。未来如果某个 API 需要破坏性变更，应通过新的版本路径发布，而不是静默修改现有响应结构。