Crear, inspeccionar, encender, cambiar el tamaño y eliminar los servidores VPS. Los servidores son identificados por su uuid.
Devuelve los servidores de su cuenta, el más nuevo primero, 25 por página. Los servidores que se están borrando no están incluidos.
Permiso requerido: servers:list
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
page |
integer | No | Número de página, a partir de 1 |
page_size |
integer | No | Resultados por página (por defecto 25, máximo 100) |
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
}
]
}
| Campo | Tipo | Descripción |
|---|---|---|
uuid |
string | Identificador del servidor utilizado en todos los demás puntos finales del servidor |
hostname |
string | Nombre de host que eligió al crear el servidor |
status |
string | Estado actual. Vea Valores de estado del servidor abajo. |
error_description |
string | null | Detalles del último fallo cuando el estado es error, de lo contrario nulo |
location_name |
string | Nombre de la ubicación en la que se ejecuta el servidor |
os_name |
string | Nombre del sistema operativo, sin la versión |
plan_name |
string | Resumen del plan legible, por ejemplo 1 vCPU / 2 GB RAM / 10 GB |
ipv4_addresses |
array | Direcciones IPv4 como cadenas. Vacíe hasta que el servidor se despliegue, y en los planes sin IPv4. |
ipv6_addresses |
array | Direcciones IPv6 como cadenas. Vacíe hasta que el servidor se despliegue. |
created_at |
datetime | Tiempo de creación (ISO 8601, UTC) |
deployed |
boolean | Verdadero una vez que el aprovisionamiento ha terminado |
| 200 | Lista de servidores recuperada con éxito |
| 403 | Token API no válido o falta el token o el token carece del permiso requerido |
Enlaza un nuevo servidor para su implementación y lo devuelve inmediatamente con la cola de estado. Provisión continúa en segundo plano: encuesta el punto final de estado hasta que se desplegue. Cuando el servidor está listo, sus datos de inicio de sesión se envían por correo electrónico al propietario de la cuenta.
Su cuenta necesita un método de pago guardado. Dependiendo del historial de su cuenta, una reserva de preautorización temporal de aproximadamente una semana del precio del plan (al menos 1 USD) puede ser colocada en su tarjeta antes de que se cree el servidor.
Permiso requerido: servers:create
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
hostname |
string | Sí | Al menos 3 caracteres. Letras, dígitos, guiones y períodos solamente. |
location_id |
integer | Sí | El id de una ubicación activa desde la API de ubicaciones |
plan_uuid |
string | Sí | La uuid de un plan activo de la API Planes |
operating_system_version_uuid |
string | Sí | El número de entrada activa en la lista de versiones de un sistema operativo |
ssh_key_uuids |
array | No | UUIDs de claves SSH de la API de claves SSH para instalar en el servidor |
ssh_key_ids |
array | No | Índices enteros de las teclas SSH, como alternativa a ssh_key_uuids. Si ambos se envían, se utiliza ssh_key_ids. |
ssh_key_uuid, ssh_key_id |
string, integer | No | Taquigrafía para una sola tecla SSH |
auth_method |
string | No | contraseña, ssh_key o ambas. Por defecto a contraseña, o a ambos cuando se proporcionan claves SSH. |
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 Creado con el objeto servidor completo descrito en Get Server Details. Las direcciones y vmid se rellenan una vez que finaliza la implementación.
{
"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 | Servidor creado y en cola para su implementación |
| 400 | Error de validación, por ejemplo una ubicación inactiva, una versión de plan o sistema operativo |
| 402 | No se denegó ningún método de pago en el archivo, facturas impagadas o la preautorización de la tarjeta |
| 403 | Token API no válido o falta el token o el token carece del permiso requerido |
| 429 | Su cuenta ha alcanzado el límite de creación del servidor |
Devuelve un servidor con su ubicación, plan, sistema operativo, direcciones IP y las cinco acciones más recientes.
Permiso requerido: 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"
}
]
}
El marcado de iconos SVG y la lista de versiones se acortan aquí.
| Campo | Tipo | Descripción |
|---|---|---|
vmid |
integer | null | Número de máquina virtual, establecido durante el despliegue |
location |
object | Objeto de ubicación, como devuelto por la API de ubicaciones |
plan |
object | Objeto Plan, como devolvió la API Plans |
operating_system, operating_system_version |
object | Sistema operativo y la versión instalada, según la API de Sistemas Operativos |
ipv4_addresses, ipv6_addresses |
array | Un objeto por dirección con ip, gateway, subnet y rdns (el nombre de host DNS inverso) |
recent_actions |
array | Hasta cinco acciones más recientes: ID, acción, action_display, descripción, user_email, created_at |
| 200 | Detalles del servidor recuperados con éxito |
| 404 | No encontrado, o pertenece a otra cuenta |
Una llamada ligera para realizar encuestas después de crear, encender o cambiar el tamaño de un servidor.
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
}
| Valor | Descripción |
|---|---|
queue |
Una acción (desplegar, activar, redimensionar, restaurar) está en cola o en curso |
deploying |
Los servidores creados desde el panel de control usan este estado; los servidores creados a través de la API permanecen en cola hasta que estén listos. |
on |
Correr |
off |
Apagado |
error |
La última acción falló. Vea error_descripción. |
suspended_payment |
Suspendido por facturas impagadas |
Encola una acción de alimentación. El estado del servidor cambia a cola hasta que la acción se completa.
Permiso requerido: servers:power
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
action |
string | Sí |
start: encendidoshutdown: cierre elegante, forzado si el invitado no se detienerestart: ciclo de energía dura (detenga, luego inicie)stop: actualmente realiza el mismo ciclo de alimentación que reiniciar. Utilice apagado para dejar un servidor apagado.
|
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 | La acción estaba en fila |
| 400 | Acción desaparecida o no apoyada |
| 402 | inicio rechazado porque la cuenta tiene facturas impagadas |
| 404 | No encontrado, o pertenece a otra cuenta |
Mueve el servidor a otro plan activo. El nuevo plan no puede tener menos espacio en disco que el actual, y el cuerpo de solicitud debe incluir la acción establecida para cambiar el tamaño. La capacidad de hipervisor para el nuevo plan se comprueba antes de que se haga cola, por lo que una solicitud rechazada deja el servidor sin cambios.
El servidor se apaga mientras se redimensiona y se inicia de nuevo después. Si el redimensionamiento falla, el servidor se vuelve a poner en su plan anterior y se inicia de nuevo si se estaba ejecutando. El crecimiento del disco no puede deshacerse.
Permiso requerido: servers:resize
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
action |
string | Sí | Debe cambiarse el tamaño |
new_plan_uuid |
string | Sí | El plan de mudarse a |
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"
}
Ejemplo de cambio de tamaño rechazado (409):
{
"error": "Not enough hypervisor capacity for the selected plan; the server was not changed"
}
| 200 | La acción estaba en fila |
| 400 | Falta acción o plan new_plan_uuid, inválido o inactivo, un plan con menos espacio en disco o un plan GPU (los planes GPU no pueden ser redimensionados a través de la API) |
| 404 | No encontrado, o pertenece a otra cuenta |
| 409 | Ya se está produciendo un cambio de tamaño o almacenamiento, o no hay suficiente capacidad de hipervisor para el nuevo plan |
| 503 | La capacidad no se pudo comprobar ahora mismo. El servidor no fue cambiado; vuelva a intentarlo más tarde. |
Genera una nueva contraseña raíz, la devuelve en la respuesta y encola el cambio en el servidor. La nueva contraseña también se le envía por correo electrónico. El servidor debe ser desplegado. No se necesita ningún cuerpo de solicitud.
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 | La acción estaba en fila |
| 400 | El servidor no está desplegado todavía |
| 404 | No encontrado, o pertenece a otra cuenta |
GET enumera el nombre de host DNS inverso de cada dirección IPv4 e IPv6 en el servidor. POST lo establece para una dirección. Enviar un nombre de host vacío restaura la dirección a su nombre DNS inverso predeterminado.
Permiso requerido: servers:update
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
ip |
string | Sí | Una dirección IPv4 o IPv6 asignada a este servidor |
hostname |
string | No | El nombre del host PTR. Deje vacío para restablecer el valor predeterminado. |
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"
}
Obtener respuesta:
{
"rdns": [
{"ip": "203.0.113.10", "hostname": "mail.example.com"},
{"ip": "2001:db8:2:dd::f9:6b", "hostname": "mail.example.com"}
]
}
| 400 | falta ip, o el nombre del host no se pudo establecer |
| 404 | La dirección IP no está asignada a este servidor |
Ejecuta un comando shell dentro del servidor a través del agente invitado QEMU y espera a que termine. El servidor debe ser desplegado y ejecutado, y qemu-guest-agent debe ser instalado y ejecutado en el invitado.
Permiso requerido: servers:exec
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
command |
string | Sí | Línea de comandos ejecutar con /bin/sh -c, hasta 2000 caracteres |
timeout |
integer | No | Segundos para esperar el comando, 1 a 300 (por defecto 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
}
Si el comando sigue ejecutándose cuando expira el tiempo de espera, la respuesta tiene timed_out establecido como true y exit_code establecido como null.
| 200 | Orden terminada o programada |
| 400 | Servidor no desplegado o no ejecutado, o parámetros no válidos |
| 409 | El agente invitado QEMU no se ejecuta en el servidor |
| 503 | Problema de conexión temporal. Reintentar después de la cabecera de Retry-After. |
Encola el servidor para su eliminación permanente. El servidor desaparece de la lista inmediatamente y no puede ser recuperado.
Permiso requerido: 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 | Aceptada: la solicitud estaba en cola |
| 404 | No encontrado, o pertenece a otra cuenta |
Almacena las claves públicas de SSH en tu cuenta, luego pasa sus uuids como ssh_key_uuids cuando creas un servidor. GET lista tus claves (25 por página); POST añade una.
Permiso requerido: ssh-keys:list (GET), ssh-keys:create (POST)
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
name |
string | Sí | Un nombre para reconocer la clave por, hasta 100 caracteres |
public_key |
string | Sí | La clave pública en formato OpenSSH, por ejemplo el contenido de id_ed25519.pub |
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
}
| Campo | Tipo | Descripción |
|---|---|---|
id, uuid |
integer, string | Identificadores de claves. Use uuid en ssh_key_uuids y en la URL de abajo; el id funciona en ssh_key_ids. |
fingerprint |
string | MD5 huella dactilar de la llave, computada por la plataforma |
last_used_at |
datetime | null | Cuando la clave fue instalada por última vez en un nuevo servidor |
| 201 | Clave añadida |
| 400 | Falta el nombre, o la clave pública no es una clave pública SSH válida |
GET devuelve una tecla con los campos anteriores. DELETE la elimina de su cuenta y devuelve 204 sin cuerpo. Eliminar una tecla no la elimina de los servidores en los que ya estaba instalada. Las teclas no se pueden editar: eliminar y añadir de nuevo.
Permiso requerido: 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"
Crear una copia de seguridad o una instantánea también es una acción del servidor:
POST /api/v1/servers/{uuid}/backup/: API de copias de seguridadPOST /api/v1/servers/{uuid}/snapshot/: API de instantáneas