HTTP API 规范
面向深度定制集成的 origin-api 访问令牌鉴权模型与服务接口规范——日常开发强烈建议优先使用 CLI。
常规编码 Agent 在日常开发中应始终优先使用 OriginAI CLI 或 MCP 协议进行集成。本文档所详述的底层 origin-api（基于 Supabase Edge Functions 构建）主要供官方 CLI 本身调用，以及供需要进行高级无头自动化、私有流水线搭建的开发者作为架构参考。若你并非在研发底层平台集成，通常无需直接操作此 API。
鉴权与安全架构模型
origin-api 在设计上并不采用常规的 Supabase 前端 JWT 验证机制。其核心鉴权架构如下：
- 客户端必须携带在 OriginAI Web 控制台 系统设置 → 访问令牌 中生成的个人访问令牌（Personal Access Token）。
- 服务端接收到请求后，对传入的明文令牌执行单向不可逆哈希运算，并借助特权 Service-role 客户端与底层数据库表
access_tokens.token_hash进行安全匹配。 - 该 Edge Function 在网关层以
verify_jwt = false模式运行，因而访问令牌的哈希校验直接承担了系统的关键权限边界。
关于访问令牌的生成与权限范围，参见个人访问令牌指南。
数据读取的默认数据源
| 请求参数配置 | 实际返回的数据源及适用场景 |
|---|---|
| 默认（缺省参数） | 始终返回目标项目最新已发布的权威 Release 快照。 |
read_type: "workspace" | 读取动态生效的工作区文件树（主要用于项目发布前的初次架构索引与草稿校验）。 |
release_tag: "<hash>" | 将读取基准精准固定为特定历史版本的 Release 快照。 |
首次发布后的受控演进闭环
在接口设计上，系统特意不设立独立的 create_change_request 动作（Action）。在项目发布首个 Release 版本后，首次执行 write_document 或 delete_document 写入时，系统将自动创建一条变更请求（返回 suggested: true 及新生成的 proposal_id，即变更请求全局唯一标识）。底层系统内核与数据表依然沿用 *_proposal 命名规范。
一条完备的变更请求生命周期标准调用链路如下：
- 调用
list_proposals（传参status: "all"）：主动读取历史驳回记录dismiss_reason，避免机械重复提交已被否决的相同设计。 - 运行
validate校验语法合规性，随后调用write_document发起修改（可传入proposal_id继续向已有单据追加，或指定new_proposal: true另立单据）。 - 调用
describe_proposal结构化补充业务背景：涵盖关联 Issue 诉求（title、note）与关键设计决策 Decisions 及变更日志 Changelog（rationale）。 - 在当前波次的所有文件写入与描述完备后，调用
submit_proposal正式标记就绪。
请注意：调用 describe_proposal 仅沉淀元数据，并不会改变单据的就绪状态；而最终的确认应用（Apply）、原因驳回（Dismiss）与结论定夺（Ready / Not ready）仅允许人类在 Web 界面中执行。接口在返回 write_document 暂存、describe_proposal 以及 submit_proposal 结果时，会附带结构化的 next 建议字段，指引客户端 Agent 明确下一步应当调用的方法。
外部 Agent 默认始终读取已发布的 Release，因此暂存机制能够百分之百避免陈旧的版本认知冲撞人类在工作台中尚未完成的动态修改。
免登录的公开 Skill 发现端点
以下网络端点均属于公共只读资源，调用时完全无需携带任何身份令牌：
GET https://getoriginai.com/.well-known/agent-skills/index.jsonGET https://getoriginai.com/skills-full.txt
相关内容
- OriginAI CLI 命令行参考
- MCP 与 Agent 安装参考 —— 建立在 origin-api 之上的 Streamable HTTP 协议适配器。
- Agent Skills 规范与参考
- 个人访问令牌指南