> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/es/modulo-8-desarrollador-y-devops/01-api-cli.md).

# API REST y herramientas CLI

Cada operación que realizas en la interfaz de VergeOS se asigna directamente a una llamada a la API REST. Esto **diseño API-first** significa que todo lo que puedes pulsar en el panel —crear VMs, configurar redes, gestionar inquilinos— puede automatizarse mediante endpoints HTTP. Esta sección cubre las tres interfaces principales para acceso programático: la **API REST** en sí misma, el **script de ayuda yb-api** para automatización en el nodo, y la **CLI vrg** para la gestión remota.

## Resumen de la API REST

La API de VergeOS sigue las convenciones REST estándar con cargas JSON, y admite el ciclo de vida completo de cada recurso de la plataforma.

### Métodos HTTP

| Método     | Propósito                         | Ejemplo                       |
| ---------- | --------------------------------- | ----------------------------- |
| **GET**    | Recuperar recursos                | `GET /api/v4/vms?fields=most` |
| **POST**   | Crear recursos o activar acciones | `POST /api/v4/vms`            |
| **PUT**    | Actualizar recursos existentes    | `PUT /api/v4/vms/36`          |
| **DELETE** | Eliminar recursos                 | `DELETE /api/v4/vms/36`       |

### Parámetros de consulta

Cada solicitud GET admite filtrado y selección de campos al estilo OData:

* **`campos`** — Especifica qué campos devolver (por ejemplo, `fields=name,$key,ram` o `fields=most` para todos los campos comunes)
* **`filter`** — Expresiones de filtro al estilo OData (por ejemplo, `filter=is_snapshot eq false`)
* **`sort`** — Ordena los resultados por campo (por ejemplo, `sort=name`)
* **`limit`** / **`offset`** — Controles de paginación para conjuntos de resultados grandes

### Formatos de datos

Todas las respuestas de la API se devuelven en **formato JSON**. Los cuerpos de las solicitudes para las operaciones POST y PUT también deben ser JSON con la `cabecera Content-Type: application/json` .

### Límites de tasa

La API admite un máximo de **1.000 solicitudes por hora** por clave de API. Para automatizaciones de alto volumen, agrupa las operaciones cuando sea posible e implementa lógica de reintento con retroceso exponencial.

## Autenticación

VergeOS admite dos métodos de autenticación —autenticación HTTP básica y autenticación basada en token—, cada uno adecuado para distintos casos de uso. Las claves de API de larga duración son una variante del método por token, presentada como un token Bearer en lugar de un token de sesión:

### 1. Autenticación HTTP básica

El método más simple: pasa las credenciales directamente con cada solicitud. Todo el tráfico de la API requiere HTTPS.

```bash
curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  --basic --user "admin:password" \
  -H "Accept: application/json"
```

### 2. Autenticación basada en token (tokens de sesión)

Solicita un token de sesión enviando por POST las credenciales a `/sys/tokens`. Usa el token devuelto en las solicitudes posteriores mediante la `x-yottabyte-token` cabecera:

```bash
# Paso 1: Obtener un token
curl --basic \
  --data-ascii '{"login": "admin", "password": "secret"}' \
  --request "POST" \
  --header "Content-Type: application/json" \
  "https://vergeos.example.com/api/sys/tokens"

# La respuesta incluye la clave del token:
# {"location":"/sys/tokens/3a334...","$key":"3a334..."}

# Paso 2: Usar el token en solicitudes posteriores
curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  -H "x-yottabyte-token: 3a334..." \
  -H "Accept: application/json"

# Paso 3: Cerrar sesión al terminar
curl -X DELETE "https://vergeos.example.com/api/sys/tokens/3a334..."
```

#### Variante de token Bearer: claves de API de larga duración

Para la automatización en producción, crea claves de API persistentes mediante **Sistema → Usuarios → \[Usuario] → Claves de API**. Estas claves son una variante del token Bearer para la autenticación por token: funcionan como tokens Bearer y permanecen válidas hasta su expiración o eliminación:

```bash
curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  -H "Authorization: Bearer your-api-key-string" \
  -H "Content-Type: application/json"
```

Las claves de API admiten **listas de IP permitidas/bloqueadas** por seguridad y **fechas de caducidad**. Guárdalas en variables de entorno en lugar de codificarlas directamente:

```bash
export VERGEOS_API_KEY="your-api-key-string"
curl -X GET "https://vergeos.example.com/api/v4/system" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"
```

{% hint style="warning" %}
Las claves de API solo se muestran una vez al crearse. Si se pierden, debes eliminar la clave y crear una nueva.
{% endhint %}

## Explorador de API (Swagger)

VergeOS incluye una **página de documentación Swagger** integrada que se genera dinámicamente a partir del sistema en ejecución, mostrando todas las tablas y operaciones disponibles.

**Para acceder a ella:**

1. Inicia sesión en la interfaz de VergeOS
2. Vaya a **Sistema → Documentación de la API**
3. Explora los endpoints disponibles, consulta esquemas y prueba llamadas a la API directamente

La interfaz de Swagger te permite ejecutar llamadas a la API en el navegador y ver el `curl` comando, el cuerpo de la respuesta y las cabeceras resultantes, lo que la convierte en una excelente herramienta para prototipar scripts de automatización.

## Endpoints clave de la API

La API organiza los recursos en tablas. Estos son los endpoints más utilizados:

| Endpoint                      | Propósito                                              |
| ----------------------------- | ------------------------------------------------------ |
| `/api/v4/vms`                 | Operaciones CRUD de máquinas virtuales                 |
| `/api/v4/vm_actions`          | Operaciones de energía de VM, clonación, instantánea   |
| `/api/v4/machine_drives`      | Adjuntar/gestionar unidades de almacenamiento de la VM |
| `/api/v4/machine_nics`        | Configurar interfaces de red de la VM                  |
| `/api/v4/machine_devices`     | Passthrough de dispositivos GPU/PCI                    |
| `/api/v4/machine_status/{id}` | Estado de energía y estado de ejecución                |
| `/api/v4/vnets`               | Gestión de redes virtuales                             |
| `/api/v4/vnet_rules`          | Reglas de firewall y NAT                               |
| `/api/v4/tenants`             | Gestión de inquilinos (VDC)                            |
| `/api/v4/nodes`               | Información de nodos físicos                           |
| `/api/v4/clusters`            | Configuración del clúster                              |
| `/api/sys/tokens`             | Gestión de tokens de sesión                            |

### Introspección del esquema

Añade `/$table` a cualquier endpoint para recuperar su esquema completo de base de datos, incluidos todos los campos y tipos disponibles:

```bash
# Obtener el esquema de la tabla de VMs
curl -X GET "https://vergeos.example.com/api/v4/vms/\$table" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"
```

## Recorrido por la API del ciclo de vida de una VM

El flujo de automatización más común es aprovisionar una VM completa mediante la API. Este proceso de cuatro pasos refleja lo que hace la interfaz de usuario por detrás:

```mermaid
graph LR
    A["1. Crear VM"] --> B["2. Añadir unidad"]
    B --> C["3. Añadir NIC"]
    C --> D["4. Encender"]
    style A fill:#e8f5e9,stroke:#2e7d32
    style B fill:#e3f2fd,stroke:#1565c0
    style C fill:#fff3e0,stroke:#ef6c00
    style D fill:#fce4ec,stroke:#c62828
```

### Paso 1: Crear la VM

```bash
curl -X POST "https://vergeos.example.com/api/v4/vms" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-01",
    "description": "Servidor web de producción",
    "machine_type": "pc-q35-9.0",
    "cpu_cores": 4,
    "cpu_type": "Cascadelake-Server",
    "ram": 8192,
    "os_family": "linux",
    "boot_order": "cd",
    "uefi": true,
    "allow_hotplug": true
  }'

# Respuesta: {"location":"/v4/vms/42","$key":"42"}
```

### Paso 2: Añadir una unidad de almacenamiento

```bash
curl -X POST "https://vergeos.example.com/api/v4/machine_drives" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": 42,
    "name": "boot-disk",
    "media": "disk",
    "interface": "virtio-scsi",
    "disksize": 107374182400,
    "preferred_tier": "1"
  }'
```

### Paso 3: Añadir una interfaz de red

```bash
curl -X POST "https://vergeos.example.com/api/v4/machine_nics" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": 42,
    "vnet": 6,
    "interface": "virtio"
  }'
```

### Paso 4: Encender

```bash
curl -X POST "https://vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "vm": 42,
    "action": "poweron"
  }'
```

### Acciones adicionales

Una vez que la VM existe, puedes activar operaciones avanzadas mediante el mismo `vm_actions` endpoint:

```bash
# Clonar una VM
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "clone", "params": {"name": "web-server-clone", "quiesce": "true"}}'

# Tomar una instantánea
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "snapshot", "params": {"name": "pre-upgrade"}}'

# Apagar de forma controlada
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "poweroff"}'
```

## Script de ayuda yb-api

La `yb-api` es un contenedor de línea de comandos integrado disponible en cada nodo VergeOS mediante SSH. Simplifica las llamadas a la API gestionando por ti la autenticación, las cabeceras, la construcción de URL, la codificación de consultas y el manejo de cargas.

### Sintaxis básica

```bash
yb-api --get|--post|--put|--delete [options] /v4/<endpoint>
```

### Opciones comunes

| Bandera          | Propósito                                |
| ---------------- | ---------------------------------------- |
| `--get`          | Recuperar recursos                       |
| `--post='JSON'`  | Crear un recurso con una carga JSON      |
| `--put='JSON'`   | Actualizar un recurso con una carga JSON |
| `--delete`       | Eliminar un recurso                      |
| `--server=IP`    | Apuntar a un sistema VergeOS específico  |
| `--user=NOMBRE`  | Autenticarse como un usuario específico  |
| `--fields='...'` | Seleccionar campos a devolver            |
| `--filter='...'` | Expresión de filtro OData                |

### Ejemplos de uso

```bash
# Listar todas las VMs (excluyendo instantáneas) con estado
yb-api --get --user=admin --server=10.0.0.100 \
  --fields='name,$key,ram,machine#status#status as machine_status' \
  --filter='is_snapshot eq false' /v4/vms

# Obtener información detallada de la VM, incluidas unidades y NICs
yb-api --get --fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1

# Crear una nueva VM
yb-api --post='{"name":"api-vm","enabled":true,"os_family":"linux",
  "cpu_cores":4,"ram":"8192"}' --user=admin --server=10.0.0.100 /v4/vms

# Cambiar el nombre de una VM
yb-api --put='{"name":"new-name"}' --user=admin --server=10.0.0.100 /v4/vms/1

# Encender una VM
yb-api --post='{"vm":1, "action": "poweron"}' /v4/vm_actions

# Obtener el esquema de la tabla de VMs
yb-api --get '/v4/vms/$table'
```

{% hint style="success" %}
La `yb-api` es ideal para consultas rápidas ad hoc y para programar directamente en nodos VergeOS. Para automatización remota desde estaciones de trabajo, usa la CLI vrg o los SDK de Python/PowerShell.
{% endhint %}

## CLI vrg

La **vrg** la herramienta de línea de comandos proporciona una interfaz completa de gestión remota para VergeOS, creada en Python con más de **200 comandos** que abarcan VMs, redes, almacenamiento, inquilinos y administración del sistema.

### Instalación

La CLI vrg se distribuye a través de varios canales: elige el que mejor se adapte a tu entorno. Ninguno está restringido por sistema operativo; pipx es la ruta recomendada en todos los sistemas operativos compatibles.

```bash
# pipx (recomendado: entorno Python aislado, todos los SO)
pipx install vrg

# pip (todos los SO)
pip install vrg

# uv (todos los SO)
uv tool install vrg

# Homebrew (todos los SO que ejecutan Homebrew)
brew install verge-io/tap/vrg
```

También se publica un binario independiente (no requiere Python) para **Linux x86\_64**, **macOS ARM64**, y **Windows x86\_64** — útil para hosts Windows sin una cadena de herramientas de Python.

### Capacidades clave

### Gestión de VMs

Crea, lista, inicia, detén, toma instantáneas, clona y elimina máquinas virtuales con comandos sencillos.

### Operaciones de red

Gestiona redes virtuales, reglas de firewall, ajustes de DHCP y configuraciones de VPN.

### Control de almacenamiento

Administra volúmenes NAS, recursos compartidos CIFS/NFS y supervisa los niveles de vSAN.

### Gestión de inquilinos

Aprovisiona inquilinos, asigna recursos y gestiona entornos multiinquilino.

La CLI vrg envuelve la misma API REST documentada arriba, proporcionando autocompletado, salida formateada y una interfaz más ergonómica para las operaciones diarias desde tu estación de trabajo.

## Gestión de errores de la API

Cuando las llamadas a la API fallan, VergeOS devuelve códigos de estado HTTP estándar con cuerpos de error JSON descriptivos:

| Código de estado | Significado         | Causa común                                                               |
| ---------------- | ------------------- | ------------------------------------------------------------------------- |
| **401**          | No autorizado       | Credenciales inválidas o token caducado                                   |
| **403**          | Prohibido           | Permisos insuficientes para la operación                                  |
| **404**          | No encontrado       | El recurso no existe o el endpoint no es válido                           |
| **409**          | Conflicto           | Conflicto de estado del recurso (por ejemplo, la VM ya está en ejecución) |
| **422**          | Error de validación | Parámetros inválidos o campos obligatorios ausentes                       |
| **429**          | Limitado por tasa   | Se superó el límite de 1.000 solicitudes/hora                             |
| **500**          | Error del servidor  | Error interno — revisa los registros del sistema                          |

{% hint style="info" %}
**¿Vienes de VMware o Nutanix?**

VergeOS expone una única `/api/v4/` superficie versionada para cada operación: la interfaz de usuario en sí misma es solo un cliente de esa API. El explorador Swagger integrado se genera dinámicamente a partir del esquema en vivo del sistema en ejecución, por lo que la documentación siempre coincide con lo que la API acepta en ese momento.
{% endhint %}

## Mejores prácticas para la automatización de la API

1. **Usa claves API** para automatización en producción en lugar de tokens de sesión: no caducan por inactividad
2. **Aplica restricciones de IP** a las claves de API para limitar dónde pueden usarse
3. **Selecciona campos específicos** (`fields=name,$key,ram`) en lugar de `fields=most` para reducir el tamaño de la carga útil
4. **Implementa paginación** con `limit` y `offset` para conjuntos de resultados grandes
5. **Gestiona operaciones asíncronas** — acciones como clonar y tomar instantáneas devuelven la respuesta inmediatamente; consulta `machine_status` hasta que finalice
6. **Guarda las credenciales en variables de entorno** — nunca codifiques los tokens directamente en los scripts
7. **Usa la introspección del esquema** (`/$table`) para descubrir los campos disponibles antes de escribir automatizaciones

## ¿Qué sigue?

Ahora que entiendes la API en bruto, las páginas siguientes cubren herramientas de nivel superior que envuelven esta API en interfaces nativas del lenguaje:

* **SDK de Python (pyvergeos)** — envoltorio con anotaciones de tipo, estilo Python, con administradores de recursos y generador de filtros OData
* **Módulo de PowerShell (PSVergeOS)** — más de 200 cmdlets con soporte de canalización para automatización nativa en Windows


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/es/modulo-8-desarrollador-y-devops/01-api-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.