HTTP API 与认证
完成客户端登录，提交 Run、跟踪事件与读取结果，并复用插件调用协议。
先用 CLI 发送请求#
终端
zioon auth login zioon-cloud
zioon api GET /v1/account/me
zioon api GET /v1/marketplace/snapshot
zioon api GET /v1/capabilities/toolsapi 自动使用当前端点的已保存登录，只打印 JSON。可以用 --data 或 --data-file 提交 JSON；请求不跟随重定向，不自动重试。
自己的 HTTP 客户端如何登录#
正式服务地址为 https://runtime.zioon.tech。交互客户端使用账户设备确认流程；不要从另一个 CLI 的凭据文件复制令牌。
| 接口 | 客户端动作 |
|---|---|
| POST /v1/account/device/start，body {} | 取得 flowToken、verificationUriComplete、userCode、expiresAt 与 interval。 |
| 用户打开 verificationUriComplete | 登录并确认该客户端请求。 |
| POST /v1/account/device/poll，body {flowToken} | 按服务返回间隔轮询，pending 时继续。 |
| 取得 token 与 expiresAt | 以 Authorization: Bearer token 访问获准接口，安全保存本客户端凭据。 |
| POST /v1/account/logout，body {} | 带当前凭据撤销登录。 |
flowToken 与登录 token 都是私密数据。设备流程失效后重新开始。非交互服务使用部署管理员已经注册和授权的 workload / bearer 客户端，不使用网页登录 cookie 充当永久密钥。
提交和跟踪 Run#
终端
zioon api POST /v1/runs --data '{"prompt":"用三句话整理本周目标。"}'
zioon api GET /v1/runs/RUN_ID
zioon attach RUN_ID --jsonl| 方法与路径 | 用途 |
|---|---|
| POST /v1/runs | 提交任务；202 返回 runId。 |
| GET /v1/runs/{id} | 读取快照和终态。 |
| GET /v1/runs/{id}/projection/stream?after=0 | 用于显示的合并 SSE 事件。 |
| GET /v1/runs/{id}/events?after=0 | 读取原始事件。 |
| GET /v1/runs/{id}/events/stream?after=0 | 原始诊断 SSE。 |
| GET /v1/runs/{id}/transcript | 读取完整记录。 |
| POST /v1/runs/{id}/abort | 显式停止。 |
| POST /v1/runs/{id}/resume | 恢复可恢复的中断任务。 |
会话与插件接口#
| 接口 | 用途 |
|---|---|
| GET /v1/sessions | 列出当前账户可见的会话。 |
| POST /v1/sessions | 创建会话。 |
| POST /v1/sessions/{id}/messages | 在会话中提交消息。 |
| GET /v1/sessions/{id}/transcript | 读取会话记录。 |
| GET /v1/marketplace/snapshot | 账户扩展与安装版本。 |
| GET /v1/capabilities/tools | 真实工具定义与插件归属。 |
插件工具通过 POST /v1/runs 进入相同授权与回执流程。详见 跨入口使用插件。
断线与不确定结果#
保存最后处理的事件序号，重连时使用 after 接续。优先使用投影流显示输出，诊断时读取原始事件。
取消或超时不保证某次写入没有发生。遇到 execution_outcome_unknown 时检查文件、进程或外部服务，再决定是否继续。
最后核对：2026-10-28 · 能力以实际部署与账号权限为准