/v1。缺省本地地址为 http://127.0.0.1:8787/v1,hosted 使用配置的 HTTPS origin。/v1 是路由前缀,不证明全部开发快照 schema 相同;记录服务端构建并阅读升级提示。
按资源查找接口
当前服务器中的每条字面量管理路由均已关联操作契约草稿。对应关系只检查路由和页面存在,不证明字段穷尽准确或运行验收通过。请求与响应行为见下表,路由权限见生成清单。认证与通用约定
可信后端发送Authorization: Bearer <token>。本地 Console 可使用独立的工作区引导。API 身份解析出租户和角色,所有资源查询与绑定保持租户范围。Application Token 有显式路由白名单,不授权审批决定、账户凭据管理或任意部署修改。身份无效返回 401,Application Token 访问 owner 路由返回 403 owner_token_required。
JSON 请求使用 Content-Type: application/json。标识参数遵守对应 schema,通常为 UUID,路径值需要 URL 编码。严格 schema 拒绝未知字段。除产物字节、SSE 和空 204 外,响应为 JSON。不能认为所有 DELETE 返回 204 或所有创建返回 201,例如 Run 提交为 202。参见错误与限制。
以下只读请求要求环境中已有真实后端 Token,不创建资源:
管理路由清单
表格从 server.ts中明确的 api.get/post/put/patch/delete 注册生成,Application Token 分类调用真实权限函数。路由可能依赖启动时注入的服务;hosted 不保证提供 local 部署配置路由。“允许”仅代表角色检查,仍需通过所有权、状态、能力与请求体验证。
使用
npx tsx tooling/generate-http-doc-index.ts 重新生成,不向服务器、Provider 或模型发请求。逐接口字段、效果与 curl 工作流位于上方参考页;Provider 专有配置与可执行端到端示例仍需分别审阅。生成器也写入路由覆盖记录,已关联不等于完成。
资源契约与影响
字段约束与示例见配置、Python、TypeScript、连接、OCI、审批、对账。这些资料补充逐操作契约;精确字段、错误、副作用与请求示例以对应契约页为准。
幂等、分页与观察
Run 提交前保存精确 Session、input、origin 与 key。同请求和 key 恢复原 Run,改变内容则冲突。Session 创建及其他任意 POST 不继承该保证。传输超时可能发生在远程副作用成功后,重发前调查原对象或操作。 全局 Session、Run 列表按实现接受过滤参数;资源操作使用 limit/offset。单个 Session 的 Run 列表使用 before 时间戳和有界分页,不是全局 offset 契约。事件使用数字字符串 after 游标,每页最多 500。不能给所有端点套同一种翻页算法。 SSE/runs/:id/stream 接受 after 或 Last-Event-ID,显式 after 优先。先持久化再推送;应用将事件、去重及游标一起提交。stream.end 是无编号传输标记,之后仍查询 Run。断开连接不取消执行,见事件与状态。
其他 HTTP 入口
GET /health/live 是无认证存活探测,不是就绪证明。/local/connect 是有独立保护条件的本地引导,不是 hosted 登录。OAuth callback、预览 grant、凭据访问分别有独立处理和认证,不能当作匿名管理 API。Sandbox 内 Runtime 端点属于内部执行协议,不应传 owner Token。
本页不宣称存在 OpenAPI 下载或通用部署 API。链接的逐操作页面说明 schema、错误、副作用和示例,已在第一批收尾中对照实现审阅。生成清单本身只证明路由归属;HTTP 执行与实云验收需要各自有明确范围的证据。