服务器 API

得到 /api/v1/servers/

列出所有服务器

返回您账户中的最新服务器, 最晚的, 25个, 每页。正在删除的服务器不包含。

所需许可: servers:list

查询参数

参数	类型	必需的	说明
`page`	integer	否无	页码,从1开始
`page_size`	integer	否无	每页结果( 默认 25, 最高 100)

示例请求

cURL

Python

JavaScript

PHP

curl -X GET "https://admin.vps.org/api/v1/servers/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

url = "https://admin.vps.org/api/v1/servers/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
for server in response.json()["results"]:
    print(server["uuid"], server["hostname"], server["status"])

const response = await fetch('https://admin.vps.org/api/v1/servers/', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});

const data = await response.json();
console.log(data.results);

$ch = curl_init('https://admin.vps.org/api/v1/servers/');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer YOUR_API_TOKEN']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($data['results'] as $server) {
    echo $server['hostname'] . ' ' . $server['status'] . "\n";
}

示例回复

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b",
      "hostname": "web-01",
      "status": "on",
      "error_description": null,
      "location_name": "New Jersey",
      "plan_name": "1 vCPU / 2 GB RAM / 10 GB",
      "os_name": "Ubuntu",
      "ipv4_addresses": ["203.0.113.10"],
      "ipv6_addresses": ["2001:db8:2:dd::f9:6b"],
      "created_at": "2026-07-30T03:54:14.914364Z",
      "deployed": true
    },
    {
      "uuid": "2d7e9b40-6c1a-4f3e-8b5d-9a0c1e2f3b4d",
      "hostname": "db-01",
      "status": "queue",
      "error_description": null,
      "location_name": "New Jersey",
      "os_name": "Debian",
      "ipv4_addresses": [],
      "ipv6_addresses": [],
      "created_at": "2026-09-14T19:33:49.426508Z",
      "deployed": false
    }
  ]
}

响应字段

外地	类型	说明
`uuid`	string	用于其他服务器终端点的服务器标识符
`hostname`	string	创建服务器时您选择的主机名
`status`	string	状态。请参见以下服务器状态值。
`error_description`	string \| null	状态为错误时上次失败细节, 否则无效
`location_name`	string	服务器运行位置的名称
`os_name`	string	操作系统名称, 没有版本
`plan_name`	string	可读计划摘要,例如1 vCPU / 2 GB RAM / 10 GB
`ipv4_addresses`	array	IPv4 地址作为字符串。服务器被安装之前是空的, 计划上是空的, 没有 IPv4 。
`ipv6_addresses`	array	IPv6 地址作为字符串。在服务器被安装之前是空的。
`created_at`	datetime	创建时间(ISO 8601,世界协调时)
`deployed`	boolean	提供完成后真实无误

响应状态码

200	已成功检索服务器列表
403	遗失或无效 API 牌标牌, 或者该牌牌缺少必需的许可

邮 /api/v1/servers/

创建新服务器

将新服务器排队, 并立即以状态队列返回, 以备部署。提供继续到背景: 调查状态终点直到部署为真实。当服务器准备好后, 其登录细节会通过电子邮件发送给账户所有者。

您的账户需要一种保存的支付方法。根据您的账户历史, 在服务器创建之前, 您的卡上可以暂时持有大约一周的计划价格( 至少1美元) 的预授权持有。

所需许可: servers:create

请求体参数

参数	类型	必需的	说明
`hostname`	string	是的	至少3个字符。只有字母、数字、连字符和时段。
`location_id`	integer	是的	位于位置 API 位置的有效位置的代号
`plan_uuid`	string	是的	API计划的一项积极计划
`operating_system_version_uuid`	string	是的	操作系统版本列表中活动条目的名号
`ssh_key_uuids`	array	否无	SSH 键的 SSH 键的 UUID, 以安装在服务器上
`ssh_key_ids`	array	否无	SSH 键的整数 ID, 作为 ssh_key_uid 的替代。如果两者都发送, 则使用 ssh_key_ id 。
`ssh_key_uuid`, `ssh_key_id`	string, integer	否无	单一个SSH 键的速记
`auth_method`	string	否无	密码、 ssh_key 或两者兼有。默认密码, 或提供 SSH 键时默认密码。

示例请求

cURL

Python

JavaScript

PHP

curl -X POST "https://admin.vps.org/api/v1/servers/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "web-01",
    "location_id": 1,
    "plan_uuid": "3bc2faf6-8f8b-4978-b62d-b52ed3f858e9",
    "operating_system_version_uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "ssh_key_uuids": ["YOUR_SSH_KEY_UUID"]
  }'

import requests

url = "https://admin.vps.org/api/v1/servers/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
data = {
    "hostname": "web-01",
    "location_id": 1,
    "plan_uuid": "3bc2faf6-8f8b-4978-b62d-b52ed3f858e9",
    "operating_system_version_uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "ssh_key_uuids": ["YOUR_SSH_KEY_UUID"],
}

response = requests.post(url, headers=headers, json=data)
server = response.json()
print(response.status_code, server["uuid"], server["status"])

const response = await fetch('https://admin.vps.org/api/v1/servers/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    hostname: 'web-01',
    location_id: 1,
    plan_uuid: '3bc2faf6-8f8b-4978-b62d-b52ed3f858e9',
    operating_system_version_uuid: 'c3418f90-80a0-4e00-a7e1-d0ab1822b941',
    ssh_key_uuids: ['YOUR_SSH_KEY_UUID']
  })
});

const server = await response.json();
console.log(server.uuid, server.status);

$data = [
    'hostname' => 'web-01',
    'location_id' => 1,
    'plan_uuid' => '3bc2faf6-8f8b-4978-b62d-b52ed3f858e9',
    'operating_system_version_uuid' => 'c3418f90-80a0-4e00-a7e1-d0ab1822b941',
    'ssh_key_uuids' => ['YOUR_SSH_KEY_UUID']
];

$ch = curl_init('https://admin.vps.org/api/v1/servers/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_TOKEN',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$server = json_decode(curl_exec($ch), true);
curl_close($ch);

示例回复

201 与“ Get Server Detail” 下的完整服务器对象创建。部署完成后, 地址和 vmid 将被填入。

{
  "uuid": "5f0c8e2a-6b1d-4c3e-9a7f-2d4b6c8e0a1f",
  "hostname": "web-01",
  "vmid": null,
  "status": "queue",
  "error_description": null,
  "location": {
    "id": 1,
    "name": "New Jersey",
    "country_name": "United States",
    "is_active": true
  },
  "plan": {
    "uuid": "3bc2faf6-8f8b-4978-b62d-b52ed3f858e9",
    "cpu": 1,
    "ram": 2,
    "ram_unit": "GB",
    "disk_space": 10,
    "disk_space_total": 10240,
    "transfer": 500,
    "price": "3.50",
    "cpu_type_name": "Shared",
    "is_active": true,
    "hourly_price": "0.005",
    "monthly_price": "3.50",
    "is_gpu": false,
    "gpu_count": 0,
    "gpu_model": ""
  },
  "operating_system": {
    "id": 1,
    "name": "Ubuntu",
    "svg_icon": "<svg ...>",
    "versions": [ ... ]
  },
  "operating_system_version": {
    "uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "name": "24.04 LTS x64",
    "os_name": "Ubuntu",
    "os_svg_icon": "<svg ...>",
    "is_active": true
  },
  "ipv4_addresses": [],
  "ipv6_addresses": [],
  "deployed": false,
  "created_at": "2026-09-14T21:02:11.402113Z",
  "recent_actions": []
}

响应状态码

201	创建并排队部署服务器
400	校验错误,例如,不活动位置、计划或操作系统版本
402	档案、未付发票或预先授权卡被拒
403	遗失或无效 API 牌标牌, 或者该牌牌缺少必需的许可
429	您的账户已达到服务器创建限制

得到 /api/v1/servers/{uuid}/

获取服务器详情

返回一个服务器, 并有其位置、计划、操作系统、 IP 地址和五个最近的行动。

所需许可: servers:list

curl -X GET "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

示例回复

{
  "uuid": "8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b",
  "hostname": "web-01",
  "vmid": 1042,
  "status": "on",
  "error_description": null,
  "location": {
    "id": 1,
    "name": "New Jersey",
    "country_name": "United States",
    "is_active": true
  },
  "plan": {
    "uuid": "14186969-fbaf-43e1-9ab2-b1f1aeb66674",
    "cpu": 1,
    "ram": 2,
    "ram_unit": "GB",
    "disk_space": 25,
    "disk_space_total": 25600,
    "transfer": 1,
    "price": "5.00",
    "cpu_type_name": "Shared",
    "is_active": true,
    "hourly_price": "0.007",
    "monthly_price": "5.00",
    "is_gpu": false,
    "gpu_count": 0,
    "gpu_model": ""
  },
  "operating_system": {
    "id": 1,
    "name": "Ubuntu",
    "svg_icon": "<svg ...>",
    "versions": [ ... ]
  },
  "operating_system_version": {
    "uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "name": "24.04 LTS x64",
    "os_name": "Ubuntu",
    "os_svg_icon": "<svg ...>",
    "is_active": true
  },
  "ipv4_addresses": [
    {
      "ip": "203.0.113.10",
      "gateway": "203.0.113.1",
      "subnet": "203.0.113.0",
      "rdns": "web-01.example.com"
    }
  ],
  "ipv6_addresses": [
    {
      "ip": "2001:db8:2:dd::f9:6b",
      "gateway": "2001:db8:2:dd::f9:1",
      "subnet": "2001:db8:2:dd::f9:0",
      "rdns": "web-01.example.com"
    }
  ],
  "deployed": true,
  "created_at": "2026-07-30T03:54:14.914364Z",
  "recent_actions": [
    {
      "id": 17028,
      "action": "create",
      "action_display": "Create",
      "description": "Server deployed with VMID 1042",
      "user_email": "you@example.com",
      "created_at": "2026-07-30T03:54:32.860854Z"
    }
  ]
}

SVG 图标标记和版本列表在此缩短。

响应字段

外地	类型	说明
`vmid`	integer \| null	部署期间设置的虚拟机号
`location`	object	位置对象, 由位置 API 返回
`plan`	object	API 计划返回的计划对象
`operating_system`, `operating_system_version`	object	操作系统API返回的操作系统和安装版本
`ipv4_addresses`, `ipv6_addresses`	array	IP、网关、子网和 Rdns 的每个地址一个对象( 逆向 DNS 主机名)
`recent_actions`	array	最多五个最近的动作: id、动作、动作_ display、描述、用户_ email、创建_ at

响应状态码

200	已成功获取服务器详细信息
404	未找到, 或属于另一个账户

得到 /api/v1/servers/{uuid}/status/

Get Server 状态

创建、供电或调整服务器大小后, 轻量级的投票呼叫。

curl -X GET "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/status/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "status": "on",
  "deployed": true,
  "resizing": false
}

服务器状态值

价值	说明
`queue`	动作( 部署、电、电、变大小、恢复) 排队或正在进行中
`deploying`	正在提供。从控制面板创建的服务器使用此状态; 通过 API 创建的服务器在编队中待备就绪。
`on`	运行中
`off`	电源关闭
`error`	上次动作失败。见错误_ 描述。
`suspended_payment`	因未付发票而暂停

邮 /api/v1/servers/{uuid}/power/

控制服务器电源

将一个电动动作排成队列。服务器状态将更改为队列,直到动作完成。

所需许可: servers:power

请求体参数

参数	类型	必需的	说明
`action`	string	是的	`start`: 电源 `shutdown`: 优优优关闭,如果客人不停止,则强制关闭 `restart`: 硬电源循环( 停, 开始) `stop`: 使用关闭服务器来关闭服务器。

示例请求

cURL

Python

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/power/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "restart"}'

import requests

server_uuid = "8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b"
url = f"https://admin.vps.org/api/v1/servers/{server_uuid}/power/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.post(url, headers=headers, json={"action": "restart"})
print(response.json())

示例回复

{
  "message": "Server restart queued"
}

响应状态码

200	动作被排队
400	丢失或不支持的动作
402	启动被拒绝,因为账户有未付发票
404	未找到, 或属于另一个账户

邮 /api/v1/servers/{uuid}/resize/

调整服务器大小

将服务器移动到另一个活动计划。新计划不能拥有比当前计划少的磁盘空间,请求的正文必须包含调整大小的动作。在任何被排队之前,要检查新计划的超视像能力,所以拒绝的请求使服务器保持不变。

服务器在调整大小后关闭, 并在调整后重新开始。如果调整大小失败, 服务器将重新放回上一个计划, 如果运行中, 服务器将再次启动。磁盘增长无法取消。

所需许可: servers:resize

请求体参数

参数	类型	必需的	说明
`action`	string	是的	必须调整大小
`new_plan_uuid`	string	是的	计划改为

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/resize/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "resize", "new_plan_uuid": "5e26a4a6-bd0c-467c-abca-da036c811c3f"}'

{
  "message": "Resize queued successfully"
}

拒绝调整大小的例子(409):

{
  "error": "Not enough hypervisor capacity for the selected plan; the server was not changed"
}

响应状态码

200	动作被排队
400	缺少动作或新的 plan_uuid、无效或不活动计划、磁盘空间较少的计划或GPU计划(无法通过 API 调整 GPU 计划大小)
404	未找到, 或属于另一个账户
409	已经进行改变规模或储存的改变,或新计划没有足够超视能力
503	无法立即检查能力。服务器没有更改; 稍后重试。

邮 /api/v1/servers/{uuid}/reset-password/

重置根密码

生成新的 root 密码, 在回复中返回, 并在服务器上排队更改。新密码也通过电子邮件发给您。服务器必须被部署。不需要请求机构。

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/reset-password/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "message": "Password reset queued. New password will also be emailed to you.",
  "password": "generated-password",
  "job_id": "b6f1c7e2-3a4d-4f5e-8b9c-0d1e2f3a4b5c"
}

响应状态码

200	动作被排队
400	服务器尚未安装
404	未找到, 或属于另一个账户

得到邮 /api/v1/servers/{uuid}/rdns/

反向 DNS( PTR)

Get 列表服务器上每个 IPv4 和 IPv6 地址的 DNS 主机名。 POST 设置一个地址。发送一个空主机名将地址重新设置到默认的反向 DNS 名。

所需许可: servers:update

请求体参数 (POST)

参数	类型	必需的	说明
`ip`	string	是的	指定给此服务器的 IPv4 或 IPv6 地址
`hostname`	string	否无	PTR 主机名。留空以重置为默认值。

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/rdns/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.10", "hostname": "mail.example.com"}'

{
  "message": "Reverse DNS for 203.0.113.10 set to mail.example.com",
  "ip": "203.0.113.10",
  "hostname": "mail.example.com"
}

得到回应:

{
  "rdns": [
    {"ip": "203.0.113.10", "hostname": "mail.example.com"},
    {"ip": "2001:db8:2:dd::f9:6b", "hostname": "mail.example.com"}
  ]
}

响应状态码

400	IP 丢失, 或者主机名无法被设定
404	IP 地址未指定给此服务器

邮 /api/v1/servers/{uuid}/exec/

在服务器上运行命令

运行服务器内的一个 shell 命令, 并通过 QEMU 客机代理运行, 等待服务器完成。服务器必须被部署和运行, 并且必须安装和运行 qemu- guest- 代理。

所需许可: servers:exec

请求体参数

参数	类型	必需的	说明
`command`	string	是的	以 /bin/sh -c, 最多为 2000 字符运行的命令行
`timeout`	integer	否无	等待命令的秒数, 1 到 300 秒( 默认 30)

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/exec/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "uptime", "timeout": 30}'

{
  "stdout": " 21:14:03 up 46 days,  2:10,  0 users,  load average: 0.08, 0.03, 0.01\n",
  "stderr": "",
  "exit_code": 0,
  "timed_out": false
}

如果命令在超时结束时仍在运行, 响应已设定为真实的超时, 退出代码则设置为无效。

响应状态码

200	命令已完成或超时
400	服务器尚未部署或未运行, 或无效参数
409	QEMU 客机代理商不在服务器上运行
503	临时连接问题。在 Retry- after header 之后重试。

删除 /api/v1/servers/{uuid}/

删除服务器

将服务器排队, 以便永久删除。服务器会立即从列表中消失, 无法恢复。

所需许可: servers:delete

curl -X DELETE "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "message": "Server deletion queued"
}

响应状态码

202	接受:请求被排队
404	未找到, 或属于另一个账户

得到邮 /api/v1/ssh-keys/

SSH 键

在您的账户中存储公共 SSH 密钥, 然后在创建服务器时将其 usid 以 ssh_key_ uuid 形式传递。获取您的密钥列表( 每页25个) ; POST 添加一个。

所需许可: ssh-keys:list (GET), ssh-keys:create (POST)

请求体参数 (POST)

参数	类型	必需的	说明
`name`	string	是的	A 以最多100个字符识别密钥的字符
`public_key`	string	是的	OpenSSH 格式的公钥, 例如 id_ed25519.pub 的内容

示例请求

cURL

Python

curl -X POST "https://admin.vps.org/api/v1/ssh-keys/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... you@laptop"}'

import requests

url = "https://admin.vps.org/api/v1/ssh-keys/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

with open("/home/you/.ssh/id_ed25519.pub") as f:
    data = {"name": "laptop", "public_key": f.read().strip()}

response = requests.post(url, headers=headers, json=data)
print(response.status_code, response.json()["uuid"])

示例回复

{
  "id": 19,
  "uuid": "6e1b9c52-3f8a-4d7e-a2c4-5b9d0e1f2a3c",
  "name": "laptop",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... you@laptop",
  "fingerprint": "0b:4c:9b:48:76:e7:1d:07:b9:ac:71:90:70:f7:9a:69",
  "created_at": "2026-08-23T19:16:11.547183Z",
  "last_used_at": null
}

响应字段

外地	类型	说明
`id`, `uuid`	integer, string	密钥识别符。在 ssh_key_uuid 中使用 uid 和在下面的 URL 中使用 usid; id 以 ssh_key_id 工作。
`fingerprint`	string	由平台计算出的MD5 钥匙指纹
`last_used_at`	datetime \| null	当键上次安装在新服务器上时

响应状态码

201	添加了密钥
400	丢失名称, 或者公用密钥不是一个有效的SSH 公用密钥

得到删除 /api/v1/ssh-keys/{uuid}/

获取或删除 SSH 键

获取上面字段的返回一个密钥。 DELETE 从您的账户中移除它, 返回204, 没有正文。删除密钥时不会从已经安装的服务器上移除它。密钥无法编辑: 删除并重新添加。

所需许可: ssh-keys:list (GET), ssh-keys:delete (DELETE)

curl -X DELETE "https://admin.vps.org/api/v1/ssh-keys/6e1b9c52-3f8a-4d7e-a2c4-5b9d0e1f2a3c/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

备份和抓图

创建备份或快照也是服务器动作 :

POST /api/v1/servers/{uuid}/backup/: 备份 API
POST /api/v1/servers/{uuid}/snapshot/: 快照 API

VPS.org API

列出所有服务器

查询参数

示例请求

示例回复

响应字段

响应状态码

创建新服务器

请求体参数

示例请求

示例回复

响应状态码

获取服务器详情

示例回复

响应字段

响应状态码

Get Server 状态

服务器状态值

控制服务器电源

请求体参数

示例请求

示例回复

响应状态码

调整服务器大小

请求体参数

响应状态码

重置根密码

响应状态码

反向 DNS( PTR)

请求体参数 (POST)

响应状态码

在服务器上运行命令

请求体参数

响应状态码

删除服务器

响应状态码

SSH 键

请求体参数 (POST)

示例请求

示例回复

响应字段

响应状态码

获取或删除 SSH 键

备份和抓图