Einführung
Die öffentliche REST-API von Level ermöglicht es Ihnen, Geräte, Gruppen, Automatisierungen, Warnmeldungen, Aktualisierungen, Tags, benutzerdefinierte Felder und andere Level-Ressourcen aus Ihren eigenen Integrationen zu lesen und zu verwalten.
Die API verwendet ressourcenorientierte URLs, JSON-Anfrage- und Antworttexte sowie Standard-HTTP-Statuscodes.
Vollständige Endpunkt-Referenz: developers.level.io
⚙️ VORAUSSETZUNGEN
Level-Administratorzugang zum Erstellen und Verwalten von API-Schlüsseln.
Ein sicherer Ort zum Aufbewahren des API-Schlüssels.
Ein HTTP-Client, der Anfrage-Header senden und JSON-Antworten lesen kann.
Öffentliche API
Einen API-Schlüssel generieren
Jede API-Anfrage erfordert einen API-Schlüssel.
Gehen Sie in Level zu Einstellungen → API-Schlüssel.
Klicken Sie auf + API-Schlüssel erstellen.
Geben Sie eine Beschreibung , der die Integration identifiziert, z. B.
Monitoring dashboardoderAsset sync.Wählen Sie eine Zugriffsebene:
Nur Lesen kann Daten abrufen.
Lesen und Schreiben kann außerdem unterstützte Ressourcen erstellen, aktualisieren und löschen.
Klicken Sie auf Schlüssel erstellen.
Kopieren Sie den Schlüssel und speichern Sie ihn in Ihrem Secret-Manager.
💡 TIPP: Erstellen Sie einen Schlüssel pro Integration. So können Sie den Zugang einer Integration widerrufen oder ersetzen, ohne die anderen zu unterbrechen.
⚠️ WARNUNG: Behandeln Sie einen API-Schlüssel wie ein Passwort. Übergeben Sie ihn nicht an die Quellcodeverwaltung, platzieren Sie ihn nicht in einer Browser-Anwendung und geben Sie ihn nicht in gemeinsam genutzten Protokollen aus.
Ihre erste Anfrage senden
Die Basis-URL lautet:
https://api.level.io
Aktuelle öffentliche Endpunkte verwenden das v2 Pfad. Senden Sie den rohen API-Schlüssel im Authorization Header. Fügen Sie kein Bearer Präfix.
Das folgende Shell-Beispiel listet Geräte auf:
curl --request GET 'https://api.level.io/v2/devices?limit=20' \ --header 'Authorization: YOUR_API_KEY'
Eine erfolgreiche Listenantwort hat diese allgemeine Form:
{ "data": [ { "id": "..." } ], "has_more": true}
Fügen Sie für Anfragen mit einem JSON-Körper Folgendes ein:
Content-Type: application/json
Verwenden Sie die Level-Entwicklerdokumentation für den Pfad, die HTTP-Methode, Parameter, den Anfragekörper und das Antwortschema jedes Endpunkts.
ℹ️ HINWEIS: Die API verwendet den Schlüsselwert direkt in Authorization. Ein Authorization: Bearer ... Header authentifiziert keinen Level-API-Schlüssel.
Die API verwenden
Aktuelle Endpunkte verwenden diese HTTP-Methoden:
GETruft Ressourcen ab.POSTerstellt Ressourcen oder startet unterstützte Aktionen.PATCHaktualisiert Ressourcen.DELETEentfernt unterstützte Ressourcen.
Nur-Lesen-Schlüssel können Leseendpunkte verwenden. Eine Schreibanfrage mit einem Nur-Lesen-Schlüssel gibt 403 Forbidden.
Paginierung
Paginierte Listenendpunkte akzeptieren:
Parameter | Zweck |
| Anzahl der zurückzugebenden Datensätze. Der Standardwert ist 20, der Maximalwert ist 100. |
| Datensätze nach der angegebenen Ressourcen-ID zurückgeben. |
| Datensätze vor der angegebenen Ressourcen-ID zurückgeben. |
Wenn has_more ist true, verwenden Sie die ID des letzten Datensatzes als starting_after um die nächste Seite anzufordern:
curl --request GET 'https://api.level.io/v2/devices?limit=100&starting_after=LAST_ID' \ --header 'Authorization: YOUR_API_KEY'
Verwenden Sie die zuerst zurückgegebene ID mit ending_before beim Blättern in entgegengesetzter Richtung.
Häufige Antworten
Status | Bedeutung |
| Die Anfrage war erfolgreich. |
| Eine Ressource wurde erstellt. |
| Der Anfragekörper oder das JSON konnte nicht geparst werden. |
| Der API-Schlüssel fehlt oder ist ungültig. |
| Dem Schlüssel fehlt der Schreibzugriff, oder die Ressource befindet sich außerhalb seiner Organisation. |
| Die angeforderte Ressource existiert nicht. |
| Mindestens ein Parameter oder Wert hat die Validierung nicht bestanden. |
| Die Organisation hat die aktuelle Anfragerate überschritten. Warten Sie die Zeitspanne in |
Validierungsfehlertexte variieren je nach Endpunkt. Lesen Sie das JSON error oder errors Wert ab, bevor Sie die Anfrage wiederholen.
API-Schlüssel verwalten
Gehen Sie zu Einstellungen → API-Schlüssel um aktive Schlüssel einzusehen, einen Schlüssel zu kopieren, seine Beschreibung oder Zugriffsebene zu ändern oder ihn zu löschen.
Löschen Sie einen Schlüssel, um ihn sofort zu widerrufen. Jede Integration, die diesen Schlüssel verwendet, erhält anschließend Authentifizierungsfehler.
⚠️ WARNUNG: Identifizieren Sie vor dem Löschen eines Schlüssels jeden Dienst, der ihn verwendet. Erstellen und stellen Sie zuerst einen Ersatzschlüssel bereit, wenn die Integration verfügbar bleiben muss.
Den vollständigen Schlüsselverwaltungs-Workflow finden Sie unter Einstellungen für API-Schlüssel.
Sicherheitspraktiken
Bewahren Sie Schlüssel in einem Secret-Manager oder einer geschützten Umgebungsvariable auf.
Verwenden Sie einen separaten Schlüssel für jede Integration und Umgebung.
Wählen Sie Nur Lesen es sei denn, die Integration muss Level-Daten ändern.
Geben Sie Schlüssel nicht in clientseitigem JavaScript, mobilen Anwendungen, Screenshots oder Support-Protokollen preis.
Löschen Sie einen Schlüssel sofort, wenn Sie glauben, dass er kompromittiert wurde.
Validieren Sie Ressourcen-IDs und API-Antworten, bevor Sie Schreib- oder Löschanfragen stellen.
Häufig gestellte Fragen
Wo befindet sich die Endpunkt-Referenz? Siehe developers.level.io.
Welche API-Version sollte ich verwenden? Aktuelle öffentliche Endpunkte verwenden Pfade, die mit
/v2/.Verwendet der Authorization-Header Bearer? Nein. Senden Sie den API-Schlüssel selbst als
AuthorizationHeader-Wert.Kann ein Nur-Lesen-Schlüssel Ressourcen erstellen oder aktualisieren? Nein. Schreibanfragen mit einem Nur-Lesen-Schlüssel geben
403 Forbidden.Wie rufe ich mehr als eine Seite ab? Lesen Sie
has_more. Wenn estrue, senden Sie die zuletzt zurückgegebene ID alsstarting_after.Was soll ich tun, wenn ein Schlüssel kompromittiert wurde? Löschen Sie ihn unter Einstellungen → API-Schlüssel, erstellen Sie einen Ersatz und aktualisieren Sie die betroffene Integration.