Introducción
La API REST pública de Level te permite leer y gestionar dispositivos, grupos, automatizaciones, alertas, actualizaciones, etiquetas, campos personalizados y otros recursos de Level desde tus propias integraciones.
La API utiliza URLs orientadas a recursos, cuerpos de solicitud y respuesta en JSON, y códigos de estado HTTP estándar.
Referencia completa de endpoints: developers.level.io
⚙️ REQUISITOS PREVIOS
Acceso de administrador a Level para crear y gestionar claves de API.
Un lugar seguro donde almacenar la clave de API.
Un cliente HTTP capaz de enviar encabezados de solicitud y leer respuestas JSON.
API pública
Generar una clave de API
Cada solicitud a la API requiere una clave de API.
En Level, ve a Configuración → Claves de API.
Haz clic en + Crear clave de API.
Introduce una Descripción que identifique la integración, como
Monitoring dashboardoAsset sync.Elige un nivel de acceso:
Solo lectura puede recuperar datos.
Lectura y escritura también puede crear, actualizar y eliminar recursos compatibles.
Haz clic en Crear clave.
Copia la clave y guárdala en tu gestor de secretos.
💡 CONSEJO: Crea una clave por integración. Puedes revocar o reemplazar el acceso de una integración sin interrumpir las demás.
⚠️ ADVERTENCIA: Trata una clave de API como una contraseña. No la incluyas en el control de versiones, no la coloques en una aplicación de navegador ni la imprimas en registros compartidos.
Envía tu primera solicitud
La URL base es:
https://api.level.io
Los endpoints públicos actuales usan el v2 ruta. Envía la clave de API sin procesar en el Authorization encabezado. No añadas un Bearer prefijo.
El siguiente ejemplo de shell lista los dispositivos:
curl --request GET 'https://api.level.io/v2/devices?limit=20' \ --header 'Authorization: YOUR_API_KEY'
Una respuesta de lista exitosa tiene esta forma general:
{ "data": [ { "id": "..." } ], "has_more": true}
Para solicitudes con un cuerpo JSON, incluye:
Content-Type: application/json
Utiliza la Documentación para desarrolladores de Level para conocer la ruta, el método HTTP, los parámetros, el cuerpo de la solicitud y el esquema de respuesta de cada endpoint.
ℹ️ NOTA: La API usa el valor de la clave directamente en Authorization. Un Authorization: Bearer ... el encabezado no autentica una clave de API de Level.
Usar la API
Los endpoints actuales usan estos métodos HTTP:
GETrecupera recursos.POSTcrea recursos o inicia acciones compatibles.PATCHactualiza recursos.DELETEelimina recursos compatibles.
Las claves de solo lectura pueden usar endpoints de lectura. Una solicitud de escritura realizada con una clave de solo lectura devuelve 403 Forbidden.
Paginación
Los endpoints de lista paginados aceptan:
Parámetro | Propósito |
| Número de registros a devolver. El valor predeterminado es 20 y el máximo es 100. |
| Devuelve registros posteriores al ID de recurso indicado. |
| Devuelve registros anteriores al ID de recurso indicado. |
Cuando has_more es true, usa el ID del último registro como starting_after para solicitar la siguiente página:
curl --request GET 'https://api.level.io/v2/devices?limit=100&starting_after=LAST_ID' \ --header 'Authorization: YOUR_API_KEY'
Usa el primer ID devuelto con ending_before al paginar en la dirección opuesta.
Respuestas comunes
Estado | Significado |
| La solicitud se realizó correctamente. |
| Se creó un recurso. |
| No se pudo analizar el cuerpo de la solicitud o el JSON. |
| La clave de API falta o no es válida. |
| La clave no tiene acceso de escritura o el recurso está fuera de su organización. |
| El recurso solicitado no existe. |
| Uno o más parámetros o valores no superaron la validación. |
| La organización superó la tasa de solicitudes actual. Espera el período indicado en |
Los cuerpos de error de validación varían según el endpoint. Lee el JSON error o errors valor antes de volver a intentar la solicitud.
Gestionar claves de API
Ve a Configuración → Claves de API para revisar las claves activas, copiar una clave, cambiar su descripción o nivel de acceso, o eliminarla.
Elimina una clave para revocarla de inmediato. Cualquier integración que use esa clave comenzará a recibir errores de autenticación.
⚠️ ADVERTENCIA: Antes de eliminar una clave, identifica todos los servicios que la usan. Crea e implementa primero una clave de reemplazo cuando la integración deba permanecer disponible.
Para conocer el flujo de trabajo completo de gestión de claves, consulta Configuración de claves de API.
Prácticas de seguridad
Guarda las claves en un gestor de secretos o en una variable de entorno protegida.
Usa una clave separada para cada integración y entorno.
Elige Solo lectura a menos que la integración necesite modificar datos en Level.
No expongas las claves en JavaScript del lado del cliente, aplicaciones móviles, capturas de pantalla ni registros de soporte.
Elimina una clave de inmediato si crees que ha sido expuesta.
Valida los IDs de recursos y las respuestas de la API antes de realizar solicitudes de escritura o eliminación.
Preguntas frecuentes
¿Dónde está la referencia de endpoints? Consulta developers.level.io.
¿Qué versión de la API debo usar? Los endpoints públicos actuales usan rutas que comienzan con
/v2/.¿El encabezado de autorización usa Bearer? No. Envía la propia clave de API como
Authorizationvalor del encabezado.¿Puede una clave de solo lectura crear o actualizar recursos? No. Las solicitudes de escritura realizadas con una clave de solo lectura devuelven
403 Forbidden.¿Cómo obtengo más de una página? Lee
has_more. Cuando estrue, envía el último ID devuelto comostarting_after.¿Qué debo hacer si una clave está comprometida? Elimínala en Configuración → Claves de API, crea un reemplazo y actualiza la integración afectada.