> 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/knowledge-base/es/automation-api/verge-api-guide.md).

# Guía de la API

## Resumen

La API de VergeOS permite a los desarrolladores interactuar con el sistema VergeOS de forma programática. Proporciona acceso a operaciones del sistema como crear máquinas virtuales, administrar recursos e interactuar con los repositorios de facturación y catálogo. La API utiliza convenciones estándar similares a REST y admite múltiples métodos de autenticación. Esta guía ofrece una descripción general de la API de VergeOS, documentación de endpoints, solicitudes de ejemplo y manejo de errores.

Este documento describe el uso de la API. La información detallada de la API puede encontrarse dentro de la interfaz de usuario de VergeOS como una página de documentación Swagger, que se genera dinámicamente y muestra un listado completo de las tablas y operaciones de la API disponibles.

### Interfaz Swagger

Para acceder a la documentación Swagger en la interfaz de usuario de VergeOS:

1. **Inicie sesión** en el sistema VergeOS con credenciales válidas.
2. Seleccione **Sistema** desde el menú superior.
3. Seleccione **Documentación de la API**.
4. Se abrirá la página de documentación Swagger. Esta página proporciona ejemplos detallados para cada operación de la API, incluida la posibilidad de probar la API directamente.

   ![Ejemplo de documentación Swagger](/files/5af89b7f9437f029e6ba69d7d512d942b9a1bb16)
5. Seleccione una tabla individual y elija una de las **GET/POST/DELETE/PUT** opciones disponibles para ver y probar acciones de la API.
6. Especifique los parámetros y haga clic en el **Botón Ejecutar** para ejecutar el comando de la API. Esto devolverá la respuesta, que incluye el cuerpo de la respuesta, el encabezado y un ejemplo curl.

## Conceptos básicos de la API

### Métodos HTTP

La API de VergeOS utiliza métodos HTTP estándar como GET, POST, PUT y DELETE para la manipulación de recursos.

### Parámetros GET

* **fields**: Especifica qué campos devolver en el conjunto de resultados.
* **filter**: Filtra el conjunto de resultados según ciertos criterios.
* **sort**: Ordena los resultados por un campo especificado.
* **limit**: Limita el número de resultados devueltos.

### Autenticación

Todas las solicitudes de la API deben realizarse a través de HTTPS y requieren autenticación mediante autenticación básica de acceso o un token de sesión.

## Notas adicionales

* **Límites de velocidad**: La API admite un máximo de 1000 solicitudes por hora por clave de API.
* **Formatos de datos**: Todas las respuestas se devuelven en formato JSON.
* **Paginación**: Los endpoints que devuelven grandes conjuntos de datos admiten paginación mediante `offset` y `limit` parámetros de consulta.

***

## Autenticación

VergeOS admite dos métodos de autenticación:

1. **Autenticación HTTP básica**\
   La API solo está disponible a través de SSL.
2. **Autenticación basada en token**\
   Los desarrolladores deben solicitar un token a la API enviando una solicitud POST al `/sys/tokens` endpoint. Luego, el token se pasa en solicitudes posteriores de la API en el encabezado `x-yottabyte-token` .

### Ejemplo de solicitud de autenticación

Para obtener un token:

```bash
curl --header "X-JSON-Non-Compact: 1" --basic --data-ascii '{"login": "USERNAME", "password": "PASSWORD"}' --insecure --request "POST" --header 'Content-Type: application/json' 'https://your-verge-instance.com/api/sys/tokens'
```

Ejemplo de respuesta:

```json
{
   "location":"\\/sys\\/tokens\\/3a334563456378845634563b7b82d2efcadce9",
   "dbpath":"tokens\\/3a334563456378845634563b7b82d2efcadce9",
   "$row":1,
   "$key":"3a334563456378845634563b7b82d2efcadce9"
}
```

Utilice el token del `"$key"` campo en todas las solicitudes posteriores:

```bash
x-yottabyte-token: 3a334563456378845634563b7b82d2efcadce9
```

Para cerrar sesión, envíe una solicitud DELETE al `/sys/tokens/{token}` endpoint.

### Ejemplo de solicitud de cierre de sesión

```bash
DELETE /sys/tokens/3a334563456378845634563b7b82d2efcadce9
```

***

### Ejemplo de máquinas virtuales

El **VMs** La sección de la API de VergeOS permite a los usuarios administrar máquinas virtuales de forma programática. Incluye endpoints para listar, crear, modificar y eliminar VMs.

### Obtener una lista de máquinas virtuales

**Punto final**:\
`GET /v4/vms?fields=most`

**Descripción**:\
Recupera una lista de todas las VMs del sistema con detalles como núcleos de CPU, RAM, tipo de máquina y detalles de configuración.

**Ejemplo de solicitud**:

```bash
curl -X 'GET' \\
  'https://your-verge-instance.com/api/v4/vms?fields=most' \\
  -H 'accept: application/json' \\
  -H 'x-yottabyte-token: <your-token>'
```

**Ejemplo de respuesta**:

```json
[
  {
    "$key": 1,
    "name": "CentOS 7 (Latest) 1.0-7",
    "machine": 7,
    "cpu_cores": 2,
    "cpu_type": "Cascadelake-Server",
    "ram": 2048,
    "os_family": "linux",
    "is_snapshot": true,
    "boot_order": "cd",
    "rtc_base": "utc",
    "console": "vnc",
    "uefi": false,
    "secure_boot": false,
    "serial_port": true,
    "uuid": "d3914756-4ec5-9dfe-5c45-b28af2fd3d73",
    "created": 1724435418,
    "modified": 1724435418
  }
]
```

**Descripción general de los datos devueltos**:

* **$key**: El identificador único de la VM.
* **name**: El nombre de la máquina virtual.
* **machine**: ID de máquina asociado con la VM.
* **cpu\_cores**: Número de núcleos de CPU asignados a la VM.
* **ram**: Cantidad de RAM asignada (en MB).
* **os\_family**: Tipo de sistema operativo.
* **uuid**: Identificador único universal (UUID) de la VM.
* **created**: La marca de tiempo de creación.
* **modified**: La marca de tiempo de la última modificación.

***

### Crear una nueva máquina virtual

**Punto final**:\
`POST /v4/vms`

**Descripción**:\
Crea una nueva máquina virtual con detalles de configuración específicos, como núcleos de CPU, RAM, tipo de máquina, orden de arranque, etc.

**Ejemplo de solicitud**:

```bash
curl -X 'POST' \\
  'https://your-verge-instance.com/api/v4/vms' \\
  -H 'accept: application/json' \\
  -H 'x-yottabyte-token: <your-token>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "name": "rest",
    "description": "test",
    "machine_type": "pc-q35-9.0",
    "allow_hotplug": true,
    "cpu_cores": 1,
    "cpu_type": "Broadwell",
    "ram": 1024,
    "os_family": "linux",
    "boot_order": "cd",
    "uefi": false,
    "note": "test vm"
  }'
```

**Ejemplo de respuesta**:

```json
{
  "location": "/v4/vms/36",
  "dbpath": "vms/36",
  "$row": 36,
  "$key": "36"
}
```

**Descripción general de los datos devueltos**:

* **location**: La ubicación del recurso VM recién creado.
* **dbpath**: Ruta de base de datos de la nueva VM.
* **$row**: ID de fila de la VM.
* **$key**: Clave única para la VM.

***

### Ejemplo de redes virtuales (Vnets)

El **Vnets** La sección de la API de VergeOS permite a los usuarios administrar redes virtuales (Vnets) de forma programática. Incluye endpoints para recuperar, crear y administrar recursos de red, incluidas redes internas y externas, y permite opciones avanzadas como el limitación de velocidad.

### Recuperar detalles de Vnet

**Punto final**:\
`GET /v4/vnets?fields=most`

**Descripción**:\
Recupera una lista de todas las Vnets del sistema con detalles como tipo de red, MTU, configuración DHCP y configuración DNS.

**Ejemplo de solicitud**:

```bash
curl -X 'GET' \\
  'https://your-verge-instance.com/api/v4/vnets?fields=most' \\
  -H 'accept: application/json' \\
  -H 'x-yottabyte-token: <your-token>'
```

**Ejemplo de respuesta**:

```json
[
  {
    "$key": 6,
    "name": "Internal Test 1",
    "advanced_options": {
      "dnsmasq": [
        "--dhcp-boot=netboot.xyz.kpxe,,192.168.10.20",
        "--dhcp-match=set:efi-x86,option:client-arch,6",
        "--dhcp-boot=tag:efi-x86,netboot.xyz.efi,,192.168.10.20",
        "--dhcp-match=set:efi-x86_64,option:client-arch,7",
        "--dhcp-boot=tag:efi-x86_64,netboot.xyz.efi,,192.168.10.20",
        "--dhcp-match=set:efi-x86_64,option:client-arch,9",
        "--dhcp-boot=tag:efi-x86_64,netboot.xyz.efi,,192.168.10.20"
      ]
    },
    "type": "internal",
    "layer2_type": "vxlan",
    "network": "192.168.100.0/24",
    "mtu": 9000,
    "dhcp_enabled": true,
    "dhcp_start": "192.168.100.100",
    "dhcp_stop": "192.168.100.200",
    "rate_limit": 0,
    "rate_limit_type": "mbytes/second",
    "gateway": ""
  }
]
```

**Descripción general de los datos devueltos**:

* **$key**: El identificador único de la Vnet.
* **name**: Nombre de la red virtual.
* **advanced\_options**: Opciones avanzadas que se pasarán a los servicios que se ejecutan dentro de la red; en este ejemplo, banderas de arranque de red para dnsmasq
* **type**: Tipo de red (p. ej., "internal").
* **layer2\_type**: El tipo de red de Capa 2, como VXLAN.
* **network**: Bloque CIDR de la red.
* **mtu**: Tamaño de la Unidad Máxima de Transmisión (MTU).
* **dhcp\_enabled**: Indica si DHCP está habilitado para esta red.
* **dhcp\_start**: Dirección IP inicial para el grupo DHCP.
* **dhcp\_stop**: Dirección IP final para el grupo DHCP.
* **rate\_limit**: Límite de velocidad para la red (en mbytes/second).
* **gateway**: La puerta de enlace predeterminada para la red.

***

### Crear una red interna con limitación de velocidad

**Punto final**:\
`POST /v4/vnets`

**Descripción**:\
Crea una nueva red virtual interna con limitación de velocidad y configuración DHCP.

**Ejemplo de solicitud**:

```bash
curl -X 'POST' \\
  'https://your-verge-instance.com/api/v4/vnets' \\
  -H 'accept: application/json' \\
  -H 'x-yottabyte-token: <your-token>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "name":"int1",
    "description":"workloads",
    "type":"internal",
    "mtu":"9000",
    "network":"192.168.80.0/24",
    "gateway":"192.168.80.1",
    "dnslist":"1.1.1.1",
    "dhcp_enabled": true,
    "rate_limit": 100,
    "rate_limit_burst": 500,
    "dhcp_start":"192.168.80.100",
    "dhcp_stop":"192.168.80.200"
  }'
```

**Ejemplo de respuesta**:

```json
{
  "location": "/v4/vnets/8",
  "dbpath": "vnets/8",
  "$row": 8,
  "$key": "8"
}
```

**Descripción general de los datos devueltos**:

* **location**: La ubicación del recurso Vnet recién creado.
* **dbpath**: Ruta de base de datos de la nueva Vnet.
* **$row**: ID de fila de la Vnet.
* **$key**: Clave única para la Vnet.

***

## Recursos

A continuación se muestra un ejemplo de URL utilizada para consultar una lista de máquinas.

*Ejemplo: <https://user1:xxxxxx@server1.verge.io/api/v4/machines?fields=all>*

|           |                   |   |                        |   |                                  |      |                             |   |                                            |
| --------- | ----------------- | - | ---------------------- | - | -------------------------------- | ---- | --------------------------- | - | ------------------------------------------ |
| https\:// | usuario           | : | contraseña             | @ | servidor                         | /api | /v4/machines                | ? | filter=\&fields=all\&sort=\&limit=         |
|           | Nombre de usuario |   | Contraseña del usuario |   | Nombre de host o IP del servidor |      | Ubicación del recurso (URI) |   | Estas opciones se describen a continuación |

### Opciones GET

#### Campos

* **Especifica qué campos devolver en el conjunto de resultados (también puede ser una vista si hay una definida para el esquema de la tabla)**.
* **all** devuelve todos los campos.
* **most** devuelve la mayoría de los campos excepto los campos de argumentos y las filas.
* **summary** devuelve los campos marcados como 'summary' en su esquema.
* Ejemplo: `fields=name,email,enabled,groups[all] as all_groups,collapse(groups[name]) as first_groups_name`

Funciones de campos:

* **collapse**
* **datetime**
* **upper**
* **lower**
* **count**
* **diskspace**
* **display**
* **hex**
* **sha1**
* **sum**
* **avg**
* **min**
* **max**

#### Filtrar

* Filtra los conjuntos de resultados según criterios especificados.
* Similar a [OData](https://msdn.microsoft.com/en-us/library/gg309461\(v=crm.7\).aspx#BKMK_filter).
* Ejemplo: `filter=enabled eq true and size gt 1048576`.
* Ejemplo: `filter=cputype eq 'qemu' or cputype eq 'kvm'`.

| Operador | Descripción                                |
| -------- | ------------------------------------------ |
| *eq*     | Igual                                      |
| *ne*     | No igual                                   |
| *gt*     | Mayor que                                  |
| *ge*     | Mayor o igual que                          |
| *lt*     | Menor que                                  |
| *le*     | Menor o igual que                          |
| *bw*     | Empieza con                                |
| *ew*     | Termina con                                |
| *y*      | Y lógico                                   |
| *o*      | O lógico                                   |
| *cs*     | Contiene la cadena (sensible a mayúsculas) |
| *ct*     | Contiene texto (no sensible a mayúsculas)  |
| *rx*     | Coincidencia con expresión regular         |

#### Ordenar

* Ordena los resultados por el campo especificado.
* Ejemplo: `sort=+name`.
* Ejemplo: `sort=-id`.

#### Límite

* **limit** (entero) limita el conjunto de resultados a un número especificado de entradas. Un valor de 0 significa ilimitado.
* Ejemplo: `limit=1`.

### Códigos de respuesta HTTP genéricos

* **400 - Solicitud incorrecta**: La solicitud no era válida.
* **401 - Inicio de sesión fallido / Inicio de sesión requerido**: La autenticación falló o es requerida.
* **403 - Permiso denegado**: No tiene los permisos requeridos.
* **404 - Recurso no encontrado**: La fila o API solicitada no existe.
* **405 - No permitido**: La operación no está permitida.
* **409 - La fila existe**: El recurso ya existe.
* **422 - Validación fallida / Parámetro inválido**: La validación falló.
* **500 - Error interno del servidor**: Ocurrió un error no controlado.

#### Específico de POST

* **201 - Creado**: Se creó correctamente una nueva fila/recurso.

#### Específico de WebSocket (usado para VNC/SPICE)

* **101 - Cambio de protocolo**: El protocolo se cambió correctamente.

#### PUT/GET/DELETE

* **200 - Éxito**: La operación se completó con éxito.

***

### Definiciones de tablas del esquema

#### Tipos de campo

* **bool**
* **texto**
* **cadena**
* **num**
* **uint8**
* **uint16**
* **uint32**
* **uint64**
* **int8**
* **int16**
* **int32**
* **int64**
* **habilitado**
* **created**
* **creado\_ms**
* **creado\_us**
* **modified**
* **modificado\_ms**
* **modificado\_us**
* **nombre\_de\_archivo**
* **tamaño\_de\_archivo**
* **archivo\_usado**
* **archivo\_asignado**
* **archivo\_modificado**
* **json**
* **fila**
* **filas**

#### Propietario del esquema / campo padre

* **Campo propietario**: Si el campo propietario es nulo, se aplican los permisos normales. Si el campo propietario tiene un valor, los permisos se reemplazan por una comprobación de permisos al propietario.
* **Campo padre**: La comprobación de permisos se aplica a la propia fila y, si los permisos fallan, también se verifican los permisos en la fila padre.

***

### Esquema completo de la tabla

Para recuperar el esquema de una tabla, añada **$table** a la URI:

**/api/v4/machines/$table** (reemplaza "machines" con el nombre de la tabla).

Se te pedirá que introduzcas tus credenciales; esto requiere credenciales de administrador de VergeOS. La salida estará en formato JSON. Firefox lo muestra en un formato legible de forma predeterminada, pero otros navegadores pueden requerir exportar el JSON a un programa externo para una mejor legibilidad.

***

### Errores de ejemplo

#### Error de ejemplo (código HTTP 422)

```json
{
  "err": "Error de validación en el campo: 'dhcp_start' - 'no supera la prueba de validación'"
}
```

VergeOS utiliza códigos de estado HTTP estándar para indicar el resultado de una solicitud de API.

* **400 Solicitud incorrecta**: La solicitud no es válida o no puede procesarse.
* **401 No autorizado**: La clave de API falta o no es válida.
* **403 Prohibido**: La clave de API no tiene los permisos requeridos.
* **404 No encontrado**: El recurso no existe.
* **500 Error interno del servidor**: Se produjo un error del servidor.

***

{% hint style="info" %}
**Información del documento**

* Última actualización: 2024-11-14
* Versión de vergeOS: 4.12.6
  {% endhint %}


---

# 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/knowledge-base/es/automation-api/verge-api-guide.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.