Introduction
L'API REST publique de Level vous permet de lire et de gérer les appareils, groupes, automatisations, alertes, mises à jour, étiquettes, champs personnalisés et autres ressources Level depuis vos propres intégrations.
L'API utilise des URL orientées ressources, des corps de requête et de réponse JSON, ainsi que des codes de statut HTTP standard.
Référence complète des points de terminaison : developers.level.io
⚙️ PRÉREQUIS
Accès administrateur Level pour créer et gérer les clés API.
Un endroit sécurisé pour stocker la clé API.
Un client HTTP capable d'envoyer des en-têtes de requête et de lire des réponses JSON.
API publique
Générer une clé API
Chaque requête API nécessite une clé API.
Dans Level, accédez à Paramètres → Clés API.
Cliquez sur + Créer une clé API.
Saisissez une Description qui identifie l'intégration, par exemple
Monitoring dashboardouAsset sync.Choisissez un niveau d'accès :
Lecture seule peut récupérer des données.
Lecture et écriture peut également créer, mettre à jour et supprimer les ressources prises en charge.
Cliquez sur Créer la clé.
Copiez la clé et enregistrez-la dans votre gestionnaire de secrets.
💡 CONSEIL : Créez une clé par intégration. Vous pouvez révoquer ou remplacer l'accès d'une intégration sans interrompre les autres.
⚠️ AVERTISSEMENT : Traitez une clé API comme un mot de passe. Ne la commitez pas dans le contrôle de version, ne la placez pas dans une application navigateur, et ne l'affichez pas dans des journaux partagés.
Envoyer votre première requête
L'URL de base est :
https://api.level.io
Les points de terminaison publics actuels utilisent le v2 chemin. Envoyez la clé API brute dans le Authorization en-tête. N'ajoutez pas de Bearer préfixe.
L'exemple shell suivant liste les appareils :
curl --request GET 'https://api.level.io/v2/devices?limit=20' \ --header 'Authorization: YOUR_API_KEY'
Une réponse de liste réussie a cette forme générale :
{ "data": [ { "id": "..." } ], "has_more": true}
Pour les requêtes avec un corps JSON, incluez :
Content-Type: application/json
Utilisez la Documentation pour les développeurs Level pour le chemin, la méthode HTTP, les paramètres, le corps de la requête et le schéma de réponse de chaque point de terminaison.
ℹ️ REMARQUE : L'API utilise la valeur de la clé directement dans Authorization. Un Authorization: Bearer ... l'en-tête n'authentifie pas une clé API Level.
Utilisation de l'API
Les points de terminaison actuels utilisent ces méthodes HTTP :
GETrécupère les ressources.POSTcrée des ressources ou démarre les actions prises en charge.PATCHmet à jour les ressources.DELETEsupprime les ressources prises en charge.
Les clés en lecture seule peuvent utiliser les points de terminaison de lecture. Une requête d'écriture effectuée avec une clé en lecture seule renvoie 403 Forbidden.
Pagination
Les points de terminaison de liste paginés acceptent :
Paramètre | Objectif |
| Nombre d'enregistrements à retourner. La valeur par défaut est 20 et le maximum est 100. |
| Retourner les enregistrements après l'ID de ressource fourni. |
| Retourner les enregistrements avant l'ID de ressource fourni. |
Lorsque has_more est true, utilisez l'ID du dernier enregistrement comme starting_after pour demander la page suivante :
curl --request GET 'https://api.level.io/v2/devices?limit=100&starting_after=LAST_ID' \ --header 'Authorization: YOUR_API_KEY'
Utilisez le premier ID retourné avec ending_before lors de la pagination dans la direction opposée.
Réponses courantes
Statut | Signification |
| La requête a réussi. |
| Une ressource a été créée. |
| Le corps de la requête ou le JSON n'a pas pu être analysé. |
| La clé API est manquante ou invalide. |
| La clé ne dispose pas d'un accès en écriture, ou la ressource est en dehors de son organisation. |
| La ressource demandée n'existe pas. |
| Un ou plusieurs paramètres ou valeurs n'ont pas passé la validation. |
| L'organisation a dépassé le taux de requêtes actuel. Attendez la période indiquée dans |
Les corps d'erreur de validation varient selon le point de terminaison. Lisez le JSON error ou errors valeur avant de réessayer la requête.
Gérer les clés API
Accédez à Paramètres → Clés API pour consulter les clés actives, copier une clé, modifier sa description ou son niveau d'accès, ou la supprimer.
Supprimez une clé pour la révoquer immédiatement. Toute intégration utilisant cette clé commencera à recevoir des erreurs d'authentification.
⚠️ AVERTISSEMENT : Avant de supprimer une clé, identifiez chaque service qui l'utilise. Créez et déployez d'abord une clé de remplacement si l'intégration doit rester disponible.
Pour le flux de gestion complet des clés, consultez Paramètres des clés API.
Bonnes pratiques de sécurité
Conservez les clés dans un gestionnaire de secrets ou une variable d'environnement protégée.
Utilisez une clé distincte pour chaque intégration et environnement.
Choisissez Lecture seule sauf si l'intégration doit modifier les données Level.
N'exposez pas les clés dans du JavaScript côté client, des applications mobiles, des captures d'écran ou des journaux d'assistance.
Supprimez immédiatement une clé si vous pensez qu'elle a été compromise.
Validez les ID de ressources et les réponses API avant d'émettre des requêtes d'écriture ou de suppression.
FAQ
Où se trouve la référence des points de terminaison ? Consultez developers.level.io.
Quelle version de l'API dois-je utiliser ? Les points de terminaison publics actuels utilisent des chemins commençant par
/v2/.L'en-tête Authorization utilise-t-il Bearer ? Non. Envoyez la clé API elle-même comme valeur de
Authorizationvaleur de l'en-tête.Une clé en lecture seule peut-elle créer ou mettre à jour des ressources ? Non. Les requêtes d'écriture effectuées avec une clé en lecture seule renvoient
403 Forbidden.Comment récupérer plus d'une page ? Lisez
has_more. Lorsqu'il esttrue, envoyez le dernier ID retourné commestarting_after.Que dois-je faire si une clé est compromise ? Supprimez-la depuis Paramètres → Clés API, créez un remplacement et mettez à jour l'intégration concernée.