REST API · v1

API 参考

Avenlith API 遵循 REST 设计：接收 JSON 请求体、返回 JSON 响应，使用标准 HTTP 状态码及 Bearer 令牌认证。

基础 URLhttps://api.avenlith.com/v1

服务器

列出服务器

GET/servers

返回令牌所属项目中的全部服务器，按创建时间倒序。

参数

regionstringquery可选
按区域代码过滤，例如 `ist1`。
labelstringquery可选
按标签过滤，例如 `role=web`。
per_pageintegerquery可选
每页条数，1–200，默认 50。
cursorstringquery可选
上一页 `meta.next_cursor` 中的游标。

请求

Shell

curl -X GET https://api.avenlith.com/v1/servers \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

响应

JSON

{
  "data": [{
      "id": "srv_8f2k1",
      "name": "web-01",
      "status": "running",
      "plan": "vps-pro",
      "region": "ist1",
      "image": "ubuntu-26.04",
      "ipv4": "203.0.113.24",
      "ipv6": "2a0f:9400:7a00::1",
      "shield": "standard",
      "labels": { "role": "web" },
      "created_at": "2026-09-18T09:12:44Z"
    }],
  "meta": { "per_page": 50, "next_cursor": null }
}

创建服务器

POST/servers

创建云服务器。接口立即返回 provisioning 状态，服务器通常在 40 秒内变为 running。

参数

namestringbody必填
主机名，1–63 个字符。
planstringbody必填
套餐代码，例如 `vps-pro`。
regionstringbody必填
区域代码。
imagestringbody必填
镜像代码或快照 ID。
ssh_keysstring[]body可选
要注入的 SSH 密钥 ID。
shieldstringbody可选
`standard`（默认）、`advanced` 或 `enterprise`。
labelsobjectbody可选
用于过滤和防火墙的键值标签。

请求

Shell

curl -X POST https://api.avenlith.com/v1/servers \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "web-01", "plan": "vps-pro", "region": "ist1", "image": "ubuntu-26.04", "ssh_keys": ["key_31xa"], "shield": "advanced", "labels": { "role": "web" } }'

响应

JSON

{
  "id": "srv_8f2k1",
  "name": "web-01",
  "status": "provisioning",
  "plan": "vps-pro",
  "region": "ist1",
  "image": "ubuntu-26.04",
  "ipv4": "203.0.113.24",
  "ipv6": "2a0f:9400:7a00::1",
  "shield": "standard",
  "labels": { "role": "web" },
  "created_at": "2026-09-18T09:12:44Z"
}

获取服务器

GET/servers/{id}

返回单台服务器的信息。

参数

idstringpath必填
服务器 ID，例如 `srv_8f2k1`。

请求

Shell

curl -X GET https://api.avenlith.com/v1/servers/{id} \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

响应

JSON

{
  "id": "srv_8f2k1",
  "name": "web-01",
  "status": "running",
  "plan": "vps-pro",
  "region": "ist1",
  "image": "ubuntu-26.04",
  "ipv4": "203.0.113.24",
  "ipv6": "2a0f:9400:7a00::1",
  "shield": "standard",
  "labels": { "role": "web" },
  "created_at": "2026-09-18T09:12:44Z"
}

重启服务器

POST/servers/{id}/actions/reboot

发送 ACPI 重启。服务器无响应时使用 "hard": true 强制断电重启。

参数

idstringpath必填
服务器 ID，例如 `srv_8f2k1`。
hardbooleanbody可选
断电重启而非正常重启。

请求

Shell

curl -X POST https://api.avenlith.com/v1/servers/{id}/actions/reboot \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "hard": false }'

响应

JSON

{ "action_id": "act_2Lw9", "status": "in_progress" }

删除服务器

DELETE/servers/{id}

永久删除服务器及其磁盘，快照与备份会保留。

参数

idstringpath必填
服务器 ID，例如 `srv_8f2k1`。

请求

Shell

curl -X DELETE https://api.avenlith.com/v1/servers/{id} \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

响应

JSON

{ "deleted": true }

网络

列出私有网络

GET/networks

返回私有网络及其已接入的服务器。

参数

per_pageintegerquery可选
每页条数，1–200，默认 50。
cursorstringquery可选
上一页 `meta.next_cursor` 中的游标。

请求

Shell

curl -X GET https://api.avenlith.com/v1/networks \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

响应

JSON

{
  "data": [
    { "id": "net_5d1q", "name": "app-net", "region": "ist1", "cidr": "10.20.0.0/24", "servers": ["srv_8f2k1", "srv_9a7c3"] }
  ],
  "meta": { "per_page": 50, "next_cursor": null }
}

分配浮动 IP

POST/floating-ips/{ip}/assign

将浮动 IP 迁移到同一区域的另一台服务器，流量切换不到一秒。

参数

ipstringpath必填
浮动 IP 地址。
server_idstringbody必填
目标服务器 ID。

请求

Shell

curl -X POST https://api.avenlith.com/v1/floating-ips/{ip}/assign \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "server_id": "srv_9a7c3" }'

响应

JSON

{ "ip": "203.0.113.50", "server_id": "srv_9a7c3", "region": "ist1" }

Shield

列出攻击记录

GET/shield/attacks

返回针对项目且已缓解的攻击，包括攻击向量与峰值。

参数

sincestringquery可选
ISO 8601 日期或相对值，例如 `7d`。
targetstringquery可选
按被攻击 IP 过滤。
per_pageintegerquery可选
每页条数，1–200，默认 50。

请求

Shell

curl -X GET https://api.avenlith.com/v1/shield/attacks \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

响应

JSON

{
  "data": [
    {
      "id": "atk_9Qx2",
      "target": "203.0.113.24",
      "vectors": ["udp_amplification", "syn_flood"],
      "peak_bps": 412000000000,
      "peak_pps": 38200000,
      "started_at": "2026-09-18T21:04:11Z",
      "ended_at": "2026-09-18T21:31:40Z"
    }
  ],
  "meta": { "per_page": 50, "next_cursor": null }
}

创建过滤规则

POST/shield/rules

为某个 IP 地址的端口段应用过滤配置。

参数

targetstringbody必填
受保护的 IP 地址。
protocolstringbody必填
`tcp` 或 `udp`。
portsstringbody必填
单个端口或端口段，例如 `27015-27030`。
profilestringbody必填
配置代码，参见“过滤配置”。

请求

Shell

curl -X POST https://api.avenlith.com/v1/shield/rules \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "target": "203.0.113.24", "protocol": "udp", "ports": "27015-27030", "profile": "game-source" }'

响应

JSON

{ "id": "rule_7Fk2", "target": "203.0.113.24", "protocol": "udp", "ports": "27015-27030", "profile": "game-source", "active": true }

账户与计费

列出 SSH 密钥

GET/ssh-keys

返回可注入新服务器的 SSH 密钥。

请求

Shell

curl -X GET https://api.avenlith.com/v1/ssh-keys \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

响应

JSON

{
  "data": [
    { "id": "key_31xa", "name": "laptop", "fingerprint": "SHA256:Qm4b…9Zs", "created_at": "2026-05-02T08:00:00Z" }
  ]
}

添加 SSH 密钥

POST/ssh-keys

上传公钥，支持 Ed25519 与 3072 位及以上的 RSA。

参数

namestringbody必填
显示名称。
public_keystringbody必填
OpenSSH 格式的公钥。

请求

Shell

curl -X POST https://api.avenlith.com/v1/ssh-keys \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… you@company.com" }'

响应

JSON

{ "id": "key_31xa", "name": "laptop", "fingerprint": "SHA256:Qm4b…9Zs" }

列出账单

GET/invoices

返回账单金额及 PDF 下载链接。

参数

statusstringquery可选
`open`、`paid` 或 `overdue`。
per_pageintegerquery可选
每页条数，1–200，默认 50。
cursorstringquery可选
上一页 `meta.next_cursor` 中的游标。

请求

Shell

curl -X GET https://api.avenlith.com/v1/invoices \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

响应

JSON

{
  "data": [
    { "id": "inv_2026_0913", "status": "paid", "currency": "EUR", "total": 812.40, "issued_at": "2026-09-01", "pdf_url": "https://console.avenlith.com/invoices/inv_2026_0913.pdf" }
  ],
  "meta": { "per_page": 50, "next_cursor": null }
}