Guías

Primeros pasos

Tenga el hostname HTTPS de su tenant y una credencial con los permisos necesarios. La URL base es https://{tenant_host}/api/v1: sustituya tenant_host por el hostname de su entorno. Este sitio de documentación no es el origen de la API del tenant.

Para consultar el inventario, use GET /devices con devices:read. Las rutas de la referencia son relativas a la URL base /api/v1. Use los IDs devueltos por la API para consultar dispositivos, ejecuciones y archivos; no deduzca IDs a partir de nombres.

En colecciones, lea data.items y reutilice meta.next_cursor sin modificarlo hasta que sea null. Mantenga el mismo token, filtros y limit entre páginas. Los cursores vencen en 30 minutos; los cambios de permisos o parámetros requieren reiniciar la paginación.

Los filtros se aplican antes de paginar. La inclusión tiene un corte temporal, pero el acceso actual, la pertenencia a grupos y las eliminaciones se revisan en cada página. No hay conteo global ni snapshot transaccional entre solicitudes.

Autenticación y permisos

Envíe la credencial solo en el encabezado Authorization: Bearer. Las cookies del navegador no autentican la API. La credencial es opaca, no es JWT y este esquema no es OAuth. El ejemplo muestra solo la sintaxis y no contiene un token real.

Los permisos son independientes: autorizar una operación no autoriza las demás. Consulte la tabla siguiente y x-required-scope en la referencia. Por ejemplo, backups:run no concede runs:read, backups:metadata:read ni backups:download.

El acceso combina los dispositivos seleccionados individualmente con los miembros actuales de los grupos seleccionados. Tenant, recursos, permisos, vencimiento y revocación se verifican de nuevo en cada llamada.

Revocar bloquea nuevas llamadas sin cancelar el trabajo aceptado. Rotar invalida inmediatamente la credencial anterior. No coloque credenciales en URLs, ejemplos compartidos ni registros de diagnóstico.

Authorization: Bearer <token>

Ejecutar y seguir backups

Para iniciar, envíe POST /devices/{identifier}/runs con backups:run, Content-Type: application/json, cuerpo {} e Idempotency-Key. La respuesta 202 indica aceptación para procesamiento asíncrono, no finalización del backup. Consulte run_href con runs:read para seguir la ejecución.

Idempotency-Key acepta de 1 a 200 caracteres ASCII imprimibles, sin espacios. Reutilice la misma clave y cuerpo al repetir la misma solicitud. La clave se conserva por 24 horas y se vincula al tenant, token, ruta y cuerpo JSON normalizado. Un cuerpo divergente devuelve 409.

Una ejecución activa se reutiliza. Las nuevas solicitudes externas comparten un intervalo de 60 segundos por tenant/dispositivo. Facturación, ciclo de vida del tenant y confianza SSH siguen condicionando la operación.

Metadatos y descarga tienen permisos separados. Solo son elegibles las ejecuciones success con artefacto y validación valid o legacy_unverified. El estado legado no demuestra una evaluación consolidada de protección.

GET /backups/{identifier}/download devuelve el archivo sin redirigir a storage externo. Una falla después del inicio de la transferencia cierra la conexión sin insertar JSON en el archivo. La finalización en el servidor no prueba la recepción por el cliente. HEAD mantiene la autorización y devuelve encabezados de attachment sin recuperar el archivo, iniciar una transferencia ni enviar Content-Length dependiente del cuerpo; GET confirma la existencia en storage.

Errores y reintentos

Use error.code para decidir el tratamiento, no el mensaje traducido. Conserve correlation_id o X-Correlation-ID para diagnóstico; no son credenciales. Consulte la referencia para los códigos específicos de cada operación.

401 indica una credencial ausente, inválida, vencida, rotada o revocada. 403 indica falta del permiso requerido; la ejecución de backup también puede estar restringida por facturación. 404 puede indicar recurso ausente, tenant desconocido, recurso fuera del alcance o artefacto inexistente.

409 distingue conflictos por código: cursor_invalid exige reiniciar la paginación; idempotency_conflict indica una solicitud repetida divergente. tenant_read_only y host_key_required también restringen la ejecución. 410 indica tenant inactivo o entorno en cierre.

400 indica solicitud o JSON malformado. Ante 405, consulte Allow para conocer los métodos aceptados por el recurso, incluidos HEAD y OPTIONS donde corresponda.

422 indica parámetros, cuerpo o clave de idempotencia inválidos. 413 señala un tamaño superior al permitido; 415 exige application/json para ejecutar. 503 indica indisponibilidad de servicio, storage o persistencia de auditoría: la operación falla de forma cerrada.

Ante 429, respete Retry-After en segundos. Conserve Idempotency-Key y cuerpo al repetir la misma creación de ejecución. Los errores previos al inicio de una descarga son JSON; tras iniciarla, verifique también la integridad y recepción del archivo.

Límites y paginación

Los límites predeterminados compartidos por ventana fija de un minuto son 30 intentos por origen/tenant antes de autenticar, incluidas llamadas válidas; 120 solicitudes por token; y 600 por tenant. La configuración del backend puede cambiar estos valores. Consulte el contrato de la versión desplegada.

limit acepta de 1 a 100 elementos, con valor predeterminado 50. Los filtros desconocidos, duplicados o inválidos se rechazan. from y to en ejecuciones y backups usan UTC terminado en Z; no aceptan offsets numéricos y to no puede preceder a from.

La solicitud de ejecución acepta solo {} y tiene un límite de 16 KiB. Las descargas están sujetas al tamaño y timeout configurados; esta guía no declara un tamaño máximo universal de descarga.

Permisos por operación