API Guide

Willkommen zum API Guide! In diesem Abschnitt unserer Dokumentation finden Sie Informationen über die Nutzung unserer verfügbaren APIs. Diese Schnittstellen ermöglichen es Entwicklern, die Funktionalitäten unserer Plattform in ihre Anwendungen zu integrieren.

API Übersicht

Unsere API ist in verschiedene Teilbereiche untergliedert, die jeweils spezifische Funktionen bereitstellen. Die wichtigsten Bereiche sind:

• abilities: Rufen Sie in Alan enthaltene Fähigkeiten ab und verwalten Sie angebundene Fähigkeiten.
• chats: Nutzen Sie die vollen Chat-Funktionen von Alan und verwalten Sie Ihre Chats.
• connectors: Konfigurieren Sie Datenverbindungen und Wissensdatenbanken, um Informationen in Chats abrufbar zu machen.
• experts: Konfigurieren Sie Experten.
• files: Laden Sie Dateien hoch und verwalten diese.
• groups: Verwalten Sie Nutzergruppen.
• health: Überprüfen Sie den Status und die Verfügbarkeit der API.
• models: Erhalten Sie Informationen über verfügbare Modelle und deren Eigenschaften.
• notifications: Rufen Sie Ihre Benachrichtigungen ab.
• oai: Interagieren Sie mit Alan über ein OpenAI-kompatibles Interface.
• search: Nutzen Sie Suchfunktionalitäten, um Chats effizient zu durchsuchen.
• shares: Verwalten Sie Freigaben von Wissensdatenbanken, Experten und Fähigkeiten.
• snapshots: Verwalten und importieren Sie Chat-Snapshots.
• tenant: Konfigurieren Sie Tenant-weite Einstellungen.
• user: Verwalten Sie Nutzereinstellungen und rufen Sie Nutzerdaten ab.

Swagger Dokumentation

Zur Visualisierung und Interaktion mit unserer API bieten wir eine Swagger-Oberfläche an, die Sie unter folgender URL finden:

https://app.alan.de/api/v1/docs

Bitte beachten Sie, dass Sie sich zuvor unter https://app.alan.de/ angemeldet haben müssen.

Grundlegende Nutzung von Swagger

Die Swagger-Oberfläche ermöglicht es Ihnen, die API-Endpunkte zu durchsuchen, Anfragen zu testen und die Antworten unserer API zu sehen. Hier sind einige Schritte, um mit Swagger zu beginnen:

1. Besuchen Sie die oben genannte URL.
2. Durchsuchen Sie die Liste der verfügbaren Endpunkte.
3. Wählen Sie einen Endpunkt aus, um detaillierte Informationen zu Anfrageparametern und Antwortstrukturen zu erhalten.
4. Verwenden Sie den "Try it out"-Button, um eine Testanfrage zu senden.
5. Geben Sie erforderliche Parameter ein und führen Sie die Anfrage aus.
6. Überprüfen Sie die Antwort und den Statuscode direkt in der Swagger-Oberfläche.

Client Credentials

Der Zugriff auf die API ist grundsätzlich mit jedem gültigen Nutzertoken möglich. Für automatisierte Prozesse oder Anwendungen empfehlen wir jedoch die Verwendung von Client Credentials. Diese bieten eine sicherere und effizientere Methode zur Authentifizierung.

Was sind Client Credentials?

Client Credentials sind spezielle Zugangsdaten, die es Anwendungen ermöglichen, im eigenen Namen auf die API zuzugreifen, ohne dass ein Benutzer direkt involviert ist. Sie bestehen aus einer Client-ID und einem Client-Secret und werden hauptsächlich für serverseitige Anwendungen genutzt.

Um Client Credentials für Alan zu erhalten, wenden Sie sich bitte an unseren Support.

Beispiel

Im folgenden Beispiel wird gezeigt, wie man in Python eine Anfrage an den GET-User-Endpunkt sendet, um die Nutzerdaten abzurufen.

Zur Ausführung des Beispielcodes wird die Python-Bibliothek Authlib benötigt, die sich mit dem folgenden Befehl installieren lässt: pip install Authlib

from authlib.integrations.httpx_client import OAuth2Client
import requests

TOKEN_ENDPOINT: str = "https://app.alan.de/authentication/provider/realms/commasoft/protocol/openid-connect/token"
CLIENT_ID = "" # Hier client id eintragen
CLIENT_SECRET = ""  # Hier client secret eintragen
url = "https://app.alan.de/api/v1/user/"

oauth_client = OAuth2Client(CLIENT_ID, CLIENT_SECRET)
token = oauth_client.fetch_token(TOKEN_ENDPOINT)
headers = {"accept": "application/json", "Content-Type": "application/json",  "Authorization": f"Bearer {token['access_token']}"}
response = requests.request("GET", url, headers=headers)
print(response.text)

API-Schlüssel

Neben dem direkten Zugriff über unsere Webanwendung als Nutzer und dem API-Zugriff über Client-Credentials bietet Alan jedem Nutzer auch die Möglichkeit, direkt auf unsere API mittels API-Schlüsseln zuzugreifen. Dabei greift der Nutzer mit seinem eigenen Account auf die API zu und kann somit alle Ressourcen, die ihm auch über die Benutzeroberfläche zur Verfügung stehen, nutzen.

Wichtige Informationen zu API-Schlüsseln

• Erstellung und Verwaltung: Jeder Nutzer kann beliebig viele API-Schlüssel in seinem Namen erstellen und verwalten. Dies ermöglicht einen feingranularen, Use-Case-spezifischen Einsatz von Alan. Die Erstellung, Verlängerung und Löschung von API-Schlüsseln erfolgt über unsere API. Siehe auch Swagger Dokumentation.
• Zugriff und Berechtigungen: API-Schlüssel sind nutzergebunden, d.h. der Zugriff mittels API-Schlüsseln erfolgt im Namen des Nutzers, der den API-Schlüssel erstellt hat. Dies bedeutet, dass alle Ressourcen (Chats, Wissensdatenbanken, Freigaben, usw.) zur Verfügung stehen.
• Gültigkeitsdauer und Verlängerung: API-Schlüssel sind standardmäßig 30 Tage gültig. Die Gültigkeitsdauer kann jedoch beim Erstellen eines API-Schlüssels individuell auf einen Zeitraum von 1 bis 180 Tagen angepasst werden. Die Gültigkeitsdauer kann jederzeit und beliebig oft bis auf eine Länge von 180 Tagen verlängert werden.
• Sicherheit: API-Schlüssel werden in Alan verschlüsselt hinterlegt. Nachdem Sie einen API-Schlüssel generiert haben, müssen Sie diesen kopieren und sicher speichern, da es keine Möglichkeit gibt, einen verlorenen API-Schlüssel in Alan erneut abzurufen. Im Fall eines verlorenen Schlüssels muss dieser gelöscht und ein neuer API-Schlüssel erstellt werden.

Beispiel für die Nutzung von API-Schlüssel

Im folgenden Beispiel wird gezeigt, wie man in Python mittels API-Schlüsseln eine Anfrage an den GET-User-Endpunkt sendet, um die Nutzerdaten abzurufen. Das Beispiel kann mit Standard-Python-Bibliotheken ausgeführt werden und hat keine Abhängigkeiten.

import requests

API_KEY = ""  # Hier API-Schlüssel eintragen. Dieser sollte mit "alan-" beginnen
url = "https://app.alan.de/api/v1/user/"

headers = {"accept": "application/json", "Content-Type": "application/json",  "Authorization": f"Bearer {API_KEY}"}
response = requests.request("GET", url, headers=headers)
print(response.text)

Weiterführende Hilfe

Spezifische Hilfestellungen, um die Chat-Funktionen per API zu nutzen, finden Sie im Artikel Per API chatten.

Sollten Sie weitere Unterstützung benötigen oder Fragen zur API haben, wenden Sie sich bitte an unseren Support.

Viel Erfolg bei der Integration und Nutzung unserer APIs!