介绍

Rayrun REST API 是平台的统一接口 —— 控制台（Dashboard）与命令行（rayrun CLI）都构建在它之上，自托管部署的第三方集成也从这里接入。本分区共 12 组、68 个端点，按组分为 12 页：左侧栏即是组列表，点进任意组可见该组的完整参数表与请求 / 响应 schema。

基础信息

项	值
契约版本	Rayrun API 0.1.0（OpenAPI 3.0.3）
基地址	托管环境：https://api.rayrunos.com/v1；自托管：<实例地址>/v1
认证	Bearer Token（程序调用）或会话 Cookie（浏览器同源），见下
契约来源	仓库根 daemon/api/openapi.yaml —— 本页与各分组页均构建期由它生成，不存在手工同步

接口一览

方法徽标即 HTTP 方法；点击任意条目跳到对应组的操作详情（参数表与请求 / 响应 schema）。

系统

• 存活与依赖连通性探测 /health

认证与账号

• 密码登录 /auth/login
• 登出 /auth/logout
• 当前身份 /auth/me
• 自助注册 /auth/register
• 接受邀请 /auth/accept-invite
• 修改自己的密码 /auth/password

沙箱

• 创建沙箱 /sandboxes
• 列出沙箱 /sandboxes
• 查询单个沙箱详情 /sandboxes/{id}
• 销毁沙箱 /sandboxes/{id}
• 全量替换沙箱标签 /sandboxes/{id}/labels
• 重命名沙箱 /sandboxes/{id}/name
• 全量替换沙箱出网策略 /sandboxes/{id}/egress
• 冷停沙箱 /sandboxes/{id}/stop
• 启动已停止的沙箱 /sandboxes/{id}/start
• 暂停沙箱 /sandboxes/{id}/pause
• 恢复挂起的沙箱 /sandboxes/{id}/resume
• 沙箱日志 /sandboxes/{id}/log

执行与终端

• 执行非交互命令 /sandboxes/{id}/exec
• 开一条终端会话 /sandboxes/{id}/terminals
• 流式读终端输出 /sandboxes/{id}/terminals/{tid}/stream
• 发送按键字节 /sandboxes/{id}/terminals/{tid}/input
• 改窗口尺寸 /sandboxes/{id}/terminals/{tid}/resize
• 关闭终端会话 /sandboxes/{id}/terminals/{tid}

文件

• 列目录 /sandboxes/{id}/files
• 下载文件 /sandboxes/{id}/files/{path}
• 上传文件 /sandboxes/{id}/files/{path}

Agent 会话

• 投递 prompt /sandboxes/{id}/prompts
• 中止当前 agent 进程 /sandboxes/{id}/cancel
• SSE 事件流 /sandboxes/{id}/events

入向发布

• 发布一个沙箱内端口 /sandboxes/{id}/ingress/{port}
• 摘除一个已发布端口 /sandboxes/{id}/ingress/{port}

镜像与构建

• 可用 agent 镜像列表 /agents
• 镜像列表 /images
• 从沙箱保存镜像 /images
• 删除用户自建镜像 /images/{ref}
• 提交 Dockerfile 构建 /builds
• 构建作业历史 /builds
• 单个构建作业 /builds/{id}
• 取消构建作业 /builds/{id}
• 构建日志 /builds/{id}/log

凭证与密钥

• 内置模型厂商目录 /model-providers
• 存凭证 /credentials
• 列出凭证元数据与注入规则 /credentials
• 删除凭证 /credentials/{name}
• 注册 / 轮换 SSH 公钥 /ssh-keys
• 列出本组织 SSH 公钥元数据 /ssh-keys
• 删除 SSH 公钥 /ssh-keys/{name}
• 创建 API token /tokens
• 列出 token 元数据 /tokens
• 撤销 token /tokens/{id}

组织与成员

• 创建邀请 /invitations
• 列出本组织邀请 /invitations
• 撤销邀请 /invitations/{id}
• 列出成员 /users
• 重置成员密码 /users/{user_id}/password
• 改成员角色 /users/{user_id}

用量与账单

• 用量聚合 /usage
• 当前余额 /billing/balance
• 活跃计费告警与组织计费策略 /billing/alerts
• 账本流水 /billing/transactions
• 当前价目表 /billing/pricing
• 兑换 /redemption-codes/redeem
• 在线充值配置 /billing/recharge
• 创建充值订单 /orders
• 查询充值订单状态 /orders/{order_id}

审计

• 审计查询 /audit

认证

除 GET /health（存活探测，免认证）外，所有端点都要求认证，两种方式任选：

Bearer Token —— 程序调用的推荐方式。可以在控制台「设置 → 我的 API Token」 创建（明文只在创建响应出现一次，请立即保存），也可以用 rayrun login 自动创建并保存到 CLI 本地；随请求头发送：

curl -H "Authorization: Bearer $RAYRUN_TOKEN" \
  https://<实例地址>/v1/sandboxes

rayrun login 创建的 Token 带 source=cli 标记：它在控制台列表里只读， 网页会话不能撤销（DELETE /v1/tokens/{id} 返回 403），需在命令行执行 rayrun logout。这是来源标记，不是权限控制 —— 同一用户的 Bearer 仍可撤销它。

会话 Cookie —— 浏览器同源调用（控制台自身即如此）自动携带，无需额外设置。

认证失败返回 401；Token 撤销立即生效（无需等待过期）。