星渡 API 文档

开始使用

使用 API 自动管理当前组织的服务器和节点。由组织所有者或管理员创建密钥，按需授予权限。

接口地址：https://xingdu.app/api/v1

认证与权限

Authorization: Bearer <API_KEY>
Content-Type: application/json

组织由密钥自动确定，无需组织参数。不要混用 Cookie、Origin 或浏览器 Fetch 请求头；API 密钥用于服务端脚本，不用于网页前端。生产环境请使用 HTTPS。

各权限独立：写入权限不包含读取权限，也不包含连接凭据读取权限。密钥不能用于管理账号、账单、订阅、API 密钥、SSH 凭据或 Agent 身份。

完整密钥仅在创建时显示，有效期为 1–365 天。创建者退出组织或失去管理员权限后不可使用；永久停用请撤销密钥。撤销不会取消已排队的远程任务。

快速开始 · Python

仅使用 Python 标准库，需要 hosts:read 和 nodes:read。运行后安全输入密钥；无人值守脚本请从密钥管理服务读取，不要写入源码或日志。

import getpass
import json
import urllib.request

base = "https://xingdu.app"
key = getpass.getpass("Xingdu API key: ")

def request(method, path, payload=None):
    body = None if method == "GET" else json.dumps(payload or {}).encode()
    req = urllib.request.Request(
        base + "/api/v1" + path, data=body, method=method,
        headers={
            "Authorization": "Bearer " + key,
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(req, timeout=30) as response:
        return None if response.status == 204 else json.load(response)

for host in request("GET", "/hosts")["data"]:
    print(host["id"], host["name"])
for node in request("GET", "/nodes")["data"]:
    print(node["id"], node["name"])

接口与权限

下列路径均以 /api/v1 开头。srv_id 和 node_id 使用列表接口返回的真实资源 ID。

常用请求体

创建或更新服务器资料（POST /hosts 或 PUT /hosts/{srv_id}）：

{
  "name": "Automation server",
  "address": "vps.example.com",
  "ssh_port": 22,
  "ssh_user": "root",
  "tags": [
    "automation"
  ],
  "notes": ""
}

探测上报字段：ok（是否成功）、latency_ms（0–120000）、exit_ip（成功时的实际公网出口）、revision（当前节点版本）。这些值由你的客户端实测产生，版本不匹配会返回 409。

部署节点

先在控制台接入托管 Agent。创建服务器记录本身不会安装 Agent 或建立 SSH 连接。以下为 Trojan 安装请求体，证书与私钥须替换为完整 PEM 内容。

{
  "name": "Automation node",
  "protocol": "trojan",
  "port": 443,
  "server_name": "node.example.com",
  "certificate": "<PEM certificate chain>",
  "private_key": "<PEM private key>",
  "confirm_install": true
}

1. 向 /hosts/{srv_id}/deployments/preflight 提交上述字段，去掉 confirm_install。预检检查控制端条件和已登记端口，不验证公网连接。
2. 向 /hosts/{srv_id}/deployments 提交完整请求体。HTTP 202 表示任务已排队。
3. 定期 GET /hosts/{srv_id}/deployments，查看返回的 state。请求超时后先查询状态，避免重复安装。任务完成后再用客户端验证线路。

协议值：shadowsocks、shadowsocks2022、trojan、vless、vmess、hysteria2、tuic、anytls、http、socks、mixed、hysteria、shadowtls、snell、snell6。最后六项需要 Agent 0.14.0-dev。Shadowsocks、SOCKS5、Mixed 和 Snell 无需 TLS 字段；http 为 HTTPS 代理，hysteria 为 Hysteria 1，均需要证书。SOCKS5 / Mixed 不加密，仅限可信网络或加密隧道接入。

ShadowTLS 的 server_name 选择 www.microsoft.com、www.apple.com 或 cloud.tencent.com，不上传证书；连接信息的 credential 为 SS2022 密钥，password 为独立的 ShadowTLS v3 密码。snell 使用 v4 客户端兼容模式；snell6 是 v6 测试版。除 Hysteria 1 外，新增协议仅开放 TCP 转发，订阅按客户端能力筛选。

更新示例：PUT /hosts/{srv_id}/deployments/{node_id}，请求体 {"port":8443,"confirm":true}。更新可能短暂中断连接。

响应、错误与限流

资源响应通常为 {"data":...}；HTTP 204 没有响应体。探测上报成功返回 {"ok":true}。所有写请求（含 DELETE）均须声明 Content-Type: application/json。

{"error":{"code":"insufficient_scope","message":"..."}}

• 401：密钥无效、过期、已撤销或创建者不再具有权限。
• 403：缺少授权范围、接口不允许 API 密钥访问或混用了浏览器身份。
• 404 / 409 / 422：资源不存在、当前状态冲突或参数无效；按 error.code 和 error.message 修正请求。
• 429：触发限流。API 密钥上限为每个 API 进程每分钟 120 次，部分操作另有限制。优先遵循 Retry-After，未提供时退避重试。