API Guide

Welcome to the API Guide! In this section of our documentation, you will find information about using our available APIs. These interfaces allow developers to integrate the functionality of our platform into their applications.

API Overview

Our API is divided into various areas, each providing specific functions. The main areas are:

• abilities: Retrieve abilities included in Alan and manage connected abilities.
• chats: Use Alan's full chatting features and manage your chats.
• connectors: Configure data connectors and knowledge databases to make information available in chats.
• experts: Configure experts.
• files: Upload files and manage them.
• groups: Manage user groups.
• health: Check the status and availability of the API.
• models: Get information about available models and their properties.
• notifications: Retrieve your notifications.
• oai: Interact with Alan using an OpenAI-compatible interface.
• search: Use search functionality to efficiently search chats.
• shares: Manage shares of knowledge databases, experts and abilities.
• snapshots: Manage and import chat snapshots.
• tenant: Configure tenant-wide settings.
• user: Manage user settings and retrieve user data.

Swagger Documentation

To visualize and interact with our API, we provide a Swagger interface, which you can find at the following URL:

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

Please make sure you have signed in beforehand at https://app.alan.de/.

Basic Usage of Swagger

The Swagger interface allows you to browse the list of available endpoints, test requests, and see the responses from our API. Here are some steps to get started with Swagger:

1. Visit the URL mentioned above.
2. Browse the list of available endpoints.
3. Select an endpoint to get detailed information about request parameters and response structures.
4. Use the "Try it out" button to send a test request.
5. Enter required parameters and execute the request.
6. Review the response and status code directly in the Swagger interface.

Client Credentials

Access to the API is generally possible with any valid user token. However, for automated processes or applications, we recommend using Client Credentials. These offer a more secure and efficient method of authentication.

What are Client Credentials?

Client Credentials are special credentials that allow applications to access the API on their own behalf, without a user being directly involved. They consist of a Client ID and a Client Secret and are primarily used for server-side applications.

To obtain Client Credentials for Alan, please contact our Support Team.

Example

In the following example, we will demonstrate how to send a request to the GET-User endpoint in Python to retrieve user data.

To execute the example code, you will need the Authlib Python library, which can be installed with the following command: 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 = "" # Enter client id
CLIENT_SECRET = ""  # Enter client secret
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 Keys

In addition to direct access via our web application as a user and API access via Client Credentials, Alan also offers every user the possibility to access our API directly using API keys. In this case, the user accesses the API with their own account and can thus use all resources which are available to them via the user interface.

Important Information about API Keys

• Creation and Management: Each user can create and manage any number of API keys in their name. This allows for fine-grained, use-case-specific use of Alan. The creation, extension, and deletion of API keys are done via our API. See also Swagger Documentation.
• Access and Permissions: API keys are user-bound, meaning that access via API keys occurs in the name of the user who created the API key. This means that all resources (chats, knowledge databases, shares, etc.) are available.
• Validity Period and Extension: API keys are valid for 30 days by default. However, the validity period can be adjusted individually to a period of 1 to 180 days when creating an API key. The validity period can be extended at any time and as often as desired, up to a maximum of 180 days.
• Security: API keys are stored encrypted in Alan. After generating an API key, you must copy and store it securely, as there is no way to retrieve a lost API key in Alan. In case of a lost API key, it has do be deleted and a new one must be created.

Example use of API keys

In the following example, we will demonstrate how to send a request to the GET-User endpoint in Python to retrieve user data.

The following example shows how to send a request to to the GET-User endpoint to retrieve user data using API keys in Python. The example can be executed with standard Python libraries and has no dependencies.

Let me know if you need any further changes!

import requests

API_KEY = ""  # Enter API-Key. Should start with "alan-"
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)

Additional Help

Specific guidance on using the chat features via API can be found in the article Chatting via API.

If you need further support or have questions about the API, please contact our support team.

Good luck with the integration and use of our APIs!