HTTP API 表面与请求约定
HTTP API 表面与请求约定
Section titled “HTTP API 表面与请求约定”Viat 的管理 API用于平台/项目管理，调用 API提供已发布业务接口，两者身份不能互换。CLI 和控制台主要调用管理 API；不带 --console 的 viat call 访问调用 API。
下列路径相对实例基础 URL，包括运维配置的反代/base-path 前缀。不要在 API 基础地址添加 /ui。受信本地夹具以外应使用 HTTPS，凭据不要放进 URL、源码或共享记录。
选择正确的表面
Section titled “选择正确的表面”| 表面 | 代表路径 | 认证与含义 |
|---|---|---|
| 进程探针 | /healthz、/readyz | 刻意无需认证且豁免激活门禁；进程健康不证明激活有效或脚本可运行。 |
| 平台登录/会话 | /auth/login、/auth/refresh、/auth/sessions | 平台账号和操作对应的会话/MFA 规则，不是项目终端用户登录。 |
| 平台管理 | /users、/license、/admin/... | 路由特定的平台角色/会话规则。 |
| 项目管理 | /projects/{slug}/... | 平台认证、成员身份和操作对应的有效项目角色/PAT 限制。 |
| 已发布业务路由 | /p/{slug}/{path} | 已发布端点的认证器/门禁，不自动使用管理登录。 |
| 内置项目身份/文件/run 路由 | 项目前缀下 /p/{slug}/auth/...、/_token、/_files/...、/_runs/... | 各自有协议和权限，这些名字是平台保留路径。 |
| 概览读取 | /projects/{slug}/overview | 普通管理访问，或按登录签发、范围很窄的 vso_ reader；它不授权相邻管理路由。 |
各自契约见管理认证、端点认证、HTTP 端点及错误处理。不要仅凭 HTTP GET 就推断所需角色。
不复制 token 的管理调用
Section titled “不复制 token 的管理调用”完成平台登录后，使用 CLI 的可刷新会话：
viat call --console --method GET /versionviat call --console --method GET /projects命令先输出状态，再输出正文，不是纯 JSON。/version 返回例如 {"version":"1.1.0"} 的对象；/projects 返回该平台身份可见项目。这些读取不发布或执行脚本。限域项目 PAT 不保证能访问全局 /projects，应使用其已知项目及允许路由。
只有明确准备在未使用 slug 下创建临时项目时，才使用以下创建请求：
viat call --console --method POST /projects --body '{"slug":"api-docs-lab","name":"API Docs Lab"}'slug、name 均为必填字符串。响应是创建后的项目表示，包括服务端生成的身份/状态，不只是提交对象。已有 slug 冲突。继续前检查响应和项目规则。本示例来自源码核对；与另行实测的首个端点流程不同，这条具体调用不是已执行响应记录。
直接 HTTP 客户端应在 Authorization: Bearer ... 中提供正确凭据，在要求 JSON 的路由设置对应 Content-Type。平台 access/refresh 对有轮换语义，不能重放已消耗 refresh 凭据，也不能悄悄用其他账号替换失败会话。完整生命周期见认证参考。
名称、文件夹、方法与载荷
Section titled “名称、文件夹、方法与载荷”| 事项 | 规则 |
|---|---|
| 项目身份 | {slug} 是项目 slug，不是显示名或 UUID。 |
| 资产身份 | 文件夹内脚本/资源/工作流在对应管理路由使用裸 {name} 和 ?folder=...。CLI 的 shared/lookup 是便利限定名，不必直接成为多个 URL path segment。 |
| 编码 | 分别百分号编码动态 path segment 和 query value，不要把含 ?/# 的资源名直接拼进 URL。 |
| 端点身份 | 管理动作使用节点 UUID；调用请求使用已发布方法/路径，不是该 UUID。 |
| 创建/更新 | POST/PUT/PATCH 语义因对象而异，不能假定 PUT 总是替换、PATCH 总是 JSON Merge Patch，应看功能字段表。 |
| 省略/null/空值 | 可能代表保留、继承、清空或拒绝；空数组可能是显式策略选择。 |
| 秘密 | 普通资源表示返回摘要/脱敏，不提供秘密恢复；不要把返回掩码作为新秘密提交。 |
| 分页 | 没有统一外层。执行查询使用 items/next_before，其他数组、截断结果和游标各不相同。 |
| 测试 | 测试路由可能执行当前代码或访问资源；Test 一词不保证 dry-run。 |
例如，读取限定脚本时显式指定文件夹：
viat call --console --method GET '/projects/hello-lab/scripts/lookup?folder=shared'需要实际存在的项目/脚本和该路由读取权限。路径的精确拼写也重要：脚本使用 /{name}/test-run，工作流使用 /{name}/test_run，不要凭猜测统一连字符和下划线。
功能与 API 索引
Section titled “功能与 API 索引”以下是路由族，不代表每个前缀支持全部 CRUD 方法。完整请求/响应、条件字段、错误、权限和副作用由所属参考页说明。
| 能力 | 管理路由族 | 所属参考 |
|---|---|---|
| 项目设置/成员 | /projects/{slug}、/members、/members/{email} | 设置、协作 |
| 资源配置/Test/schema | /projects/{slug}/resources、/{name}、/{name}/test、/{name}/schema/refresh | 20 类资源参考 |
| 数据库迁移 | .../resources/{name}/migrations | CLI 数据库操作 |
| 受管文件与业务审计 | .../resources/{name}/files、.../audit、.../audit/export | Storage、审计 |
| 脚本、环境、产物 | /projects/{slug}/scripts、/{name}/env、/build、/artifact、/binary | 脚本上下文、运行时、CLI 脚本 |
| 工作流 | /projects/{slug}/workflows、/{name}/validate、/{name}/test_run | 工作流 |
| 端点/树契约 | /projects/{slug}/endpoints、/trees | HTTP、CRUD、入站 WebSocket |
| 发布 | .../endpoints/{id}/publish、/unpublish；/projects/{slug}/publish/plan、/apply、/rollback、/history | 快照、回滚 |
| 调度 | /projects/{slug}/schedules、/{name}/pause、/resume、/trigger、/runs | 调度 |
| 文件系统、RabbitMQ、出站 WebSocket | /projects/{slug}/watches、/queue-triggers、/ws-triggers | 监听、队列、WS 订阅 |
| 聊天账号/身份/触发器 | /projects/{slug}/im/accounts、/identities、/bind-links、/triggers | 个人微信及其他提供商页面 |
| 授权模型 | /projects/{slug}/authz、/types、/rules、/subject-attrs、/lint | 授权 |
| 观测 | /projects/{slug}/overview、/executions、/async-runs、/audit | Runs、日志、审计 |
| 已发布项目 OpenAPI | /projects/{slug}/openapi.json | 下节 |
同一单元格内的短后缀相对紧邻的路由族，不是全局路由。存在 API 能力，不代表存在对应 CLI 命令或 MCP 工具；CLI、MCP均有明确清单。
导出已发布应用的 OpenAPI
Section titled “导出已发布应用的 OpenAPI”经过认证的项目成员可请求：
viat call --console --method GET /projects/hello-lab/openapi.json文档使用 OpenAPI 3.1.0，从当前活动已发布快照及认证器元数据构建。servers 指向实例 base path 加 /p/{slug}。草稿编辑不自动改变活动快照所代表的公开契约。生成的 info.version 不是运行服务端发行版本，应使用 /version 核对后者。
该导出描述项目已发布的调用接口，不是完整管理 API 规范。它刻意放在成员认证的管理路由，而不是公开 /p/{slug}/_openapi.json，不要编造后者。成员可审阅并向集成方提供脱敏契约，但文档本身不签发调用凭据，也不豁免 authz 门禁。使用客户端生成器前，应阅读流式、异步、代理/CRUD 及 schema 限制说明，不能假定生成器编码了全部运行规则。
验证与安全清理
Section titled “验证与安全清理”集成应先读取、记录实际对象 ID，再仅在隔离命名空间执行明确打算进行的修改，同时检查状态和操作专属结果字段。发布不代表所有构建就绪，异步接受不代表完成，资源 Test 可能 HTTP 200 但 ok: false；通用判断见错误与结果边界。
停止相关触发器、解决依赖后，只移除集成自己创建的对象。导出 API 契约/日志即使不含秘密，也可能暴露私有路由或数据，应私下保存并明确清理临时副本。本页不会执行管理示例，也不授权生产清理。
固定源码 03751a67：crates/viat-api/src/lib.rs 路由装配、dto.rs、各 handler、handlers/openapi.rs/openapi.rs，以及 CLI commands/{endpoint,script}.rs。资源/语言/CLI/MCP 契约单独固定，不冒充完整自动生成的管理 OpenAPI。