---
title: AIlon Developer-Dokumentation — Public API v1 & MCP-Server
description: "Referenzdokumentation von AIlon: Projekte, Zielgruppen und Insight-Daten per REST-API abrufen oder per MCP-Server direkt in Claude, ChatGPT und Cursor nutzen."
image: https://ailon.io/hubfs/Awaken-Audiences-Detail-transparent-Dark.png
---

[![AIlon](https://ailon.io/hubfs/AIlon_color+white.png)](https://ailon.io/?hsLang=de)

AIlon Developer-DokuPublic API v1 · MCP-Server

Grundlagen

[·Übersicht](https://ailon.io/integration-dokumentation#overview) [·Zugänge im Vergleich](https://ailon.io/integration-dokumentation#zugaenge) [·Lizenzen](https://ailon.io/integration-dokumentation#lizenzen) [·Zugang & Authentifizierung](https://ailon.io/integration-dokumentation#auth) [·Organisationen & Rechte](https://ailon.io/integration-dokumentation#rollen) [·Kostenlose Beispielprojekte](https://ailon.io/integration-dokumentation#free-usage) [·Credits & Abrechnung](https://ailon.io/integration-dokumentation#credits) [·Datenschutz & Betrieb](https://ailon.io/integration-dokumentation#privacy) [·Referenz für KI-Agenten](https://ailon.io/integration-dokumentation#agent-reference)

REST API · v1

[·Schnellstart](https://ailon.io/integration-dokumentation#quickstart) [·Endpunkt-Übersicht](https://ailon.io/integration-dokumentation#endpoints) [·Pagination](https://ailon.io/integration-dokumentation#pagination)

Erste Schritte

[GET/health/](https://ailon.io/integration-dokumentation#get-health) [GET/whoami/](https://ailon.io/integration-dokumentation#get-whoami)

Projekte & Zielgruppen

[GET/projects/](https://ailon.io/integration-dokumentation#get-projects) [POST/projects/](https://ailon.io/integration-dokumentation#post-projects) [GET/projects/{id}/](https://ailon.io/integration-dokumentation#get-project) [POSTgenerate\_audience/](https://ailon.io/integration-dokumentation#post-generate-audience) [GETaudiences/](https://ailon.io/integration-dokumentation#get-audiences) [GETaudiences/{id}/](https://ailon.io/integration-dokumentation#get-audience) [GET.../potential/](https://ailon.io/integration-dokumentation#get-potential) [GET.../summary/](https://ailon.io/integration-dokumentation#get-summary)

Insights

[GET/insights/](https://ailon.io/integration-dokumentation#get-insights) [GET.../data/](https://ailon.io/integration-dokumentation#get-insight-data) [GET.../credit-cost/](https://ailon.io/integration-dokumentation#get-insight-credit-cost) [GET.../features/](https://ailon.io/integration-dokumentation#get-insight-features) [GETfeatures/{id}/](https://ailon.io/integration-dokumentation#get-insight-feature)

Nutzung & Abrechnung

[GET/usage/](https://ailon.io/integration-dokumentation#get-usage) [GETcredit-limit/](https://ailon.io/integration-dokumentation#get-credit-limit) [GETusage/requests/](https://ailon.io/integration-dokumentation#get-requests) [GETusage/ledger/](https://ailon.io/integration-dokumentation#get-ledger) [GETusage/keys/](https://ailon.io/integration-dokumentation#get-keys)

MCP-Server

[MCPÜberblick](https://ailon.io/integration-dokumentation#mcp) [·Einrichtung](https://ailon.io/integration-dokumentation#mcp-setup) [·Clients verbinden](https://ailon.io/integration-dokumentation#mcp-clients) [·Tool-Referenz](https://ailon.io/integration-dokumentation#mcp-tools) [·Playbooks](https://ailon.io/integration-dokumentation#mcp-playbooks) [·Troubleshooting](https://ailon.io/integration-dokumentation#mcp-trouble)

Referenz

[·Tool ↔ Endpunkt](https://ailon.io/integration-dokumentation#bridge) [·Status & Fehlercodes](https://ailon.io/integration-dokumentation#statuses) [·Datenmodelle](https://ailon.io/integration-dokumentation#schemas) [·Fehlende Merkmale](https://ailon.io/integration-dokumentation#missing)

☰ Menü

● Public API v1 · MCP-Server

# Zielgruppen definieren, analysieren, verstehen.

AIlon gibt Ihnen programmatischen Zugriff auf Projekte, Zielgruppen und Insight-Daten — dieselben Daten, die Ihre Nutzer im AIlon-Dashboard sehen. Sie können Zielgruppen per natürlicher Sprache erzeugen und deren demografische und verhaltensbezogene Merkmale gegen den Bevölkerungsdurchschnitt auswerten. Dafür stehen zwei Zugänge bereit.

Zugang A

### REST API

Für die Integration in eigene Produkte, Dashboards, CDP- und BI-Systeme. Sie bauen die Aufrufe selbst und behalten volle Kontrolle über Ablauf und Fehlerbehandlung. Antwortformat `application/json`.

dashboard.ailon.io/public-api/v1/

Zugang B

### MCP-Server

Für KI-Agenten und Chat-Clients wie Claude, ChatGPT oder Cursor. Einmal verbinden, danach arbeitet der Agent direkt mit AIlon — ohne eigene Integration.

https://mcp.ailon.io

Beispiel · GET /insights/{id}/data/ → Feature „Alter“, Index gegenüber Bevölkerung (100 = Ø)

18–24 Jahre

76

25–34 Jahre

142

35–44 Jahre

118

45+ Jahre

61

index\_value \> 100 → in dieser Zielgruppe überrepräsentiert · \< 100 → unterrepräsentiert. Illustrative Beispielwerte.

## Zugänge im Vergleich

Beide Zugänge sprechen dieselbe Datenbasis, dasselbe Rechtemodell und dasselbe Guthaben an. Was für Authentifizierung, Beispielprojekte, Credits und Fehlercodes gilt, gilt für beide.

|  | REST API | MCP-Server |
| --- | --- | --- |
| **Geeignet für** | eigene Anwendungen, Automatisierung, Reporting | KI-Agenten, Chat-Clients, Analyse im Dialog |
| **Voraussetzung** | Entwicklungsumgebung | MCP-fähiger Client, kein Code |
| **Adresse** | `dashboard.ailon.io/public-api/v1/` | `mcp.ailon.io` |
| **Umfang** | 20 Endpunkte | 10 Tools |
| **Nur hier verfügbar** | Nutzungsprotokoll, Credit-Ledger, Key-Verwaltung, Kostenvorschau | semantische Merkmalssuche, Playbooks |
| **Datenbasis** | identisch — dieselben Projekte, Zielgruppen und Merkmale |  |
| **Guthaben** | identisch — ein Credit-Konto, siehe [Credits & Abrechnung](https://ailon.io/integration-dokumentation#credits) |  |
| **Beispielprojekte** | identisch kostenfrei, siehe [Beispielprojekte](https://ailon.io/integration-dokumentation#free-usage) |  |

**Wechsel ist jederzeit möglich.** Viele Teams beginnen im Chat über MCP und überführen den Ablauf später in eigenen Code. Welches Tool welchem Endpunkt entspricht, steht in der [Gegenüberstellung Tool ↔ Endpunkt](https://ailon.io/integration-dokumentation#bridge).

## Lizenzen

AIlon ist als Dashboard und als programmatischer Zugang verfügbar — das sind zwei getrennte Lizenzen:

- Die **Dashboard-Lizenz** gibt Zugriff auf `dashboard.ailon.io`.
- Die **API-/MCP-Lizenz** stellt das Credit-Guthaben für programmatische Abfragen bereit. Sie deckt beide Zugänge ab: REST und MCP erfordern keine separaten Lizenzen.

**Eine Datenschicht darunter.** Projekte und Zielgruppen, die über einen der Wege entstehen, sind in allen anderen sichtbar — im Dashboard angelegte Zielgruppen lassen sich per API auswerten und umgekehrt.

## Zugang & Authentifizierung

Der Zugang ist benutzerbezogen: Sichtbar sind ausschließlich Projekte und Zielgruppen, auf die dieser Benutzer im Dashboard Zugriff hat. Das gilt unabhängig davon, ob der Zugriff über die REST-API oder über den MCP-Server erfolgt.

### API-Key erhalten

Den Key erzeugen Sie selbst im Dashboard: auf der Startseite von [dashboard.ailon.io](https://dashboard.ailon.io) rechts in der Karte **AIlon Integrationen**. Ein Kontakt zum Support ist nicht nötig.

Der Präfix (`api_key_prefix` aus `/whoami/`) dient nur der Zuordnung und ist nicht geheim. Den geheimen Teil bewahren Sie sicher auf — er wird nicht erneut angezeigt.

### REST API · Bearer-Token

Jede Anfrage außer `GET /health/` benötigt folgenden Header. Ein ungültiger oder fehlender Key führt zu `401 Unauthorized`.

```
Authorization: Bearer ailpk_….IhrGeheimerTeil
```

### MCP-Server · OAuth

Der MCP-Server nutzt keinen manuell hinterlegten Key, sondern OAuth 2 mit PKCE. Sie tragen im Client lediglich die Server-URL ein; alles Weitere läuft über den Browser:

1. **Weiterleitung.** Der Client öffnet die AIlon-Anmeldung. Sind Sie noch nicht angemeldet, erscheint zuerst die normale Anmeldemaske.
2. **Bestätigung.** AIlon zeigt den angemeldeten Benutzer, die Organisation und die angefragte Berechtigung *Access AIlon MCP tools*.
3. **Rücksprung.** Nach *Authorize* springt der Browser zurück in den Client, die Verbindung steht.

Die Freigabe gilt pro Client — ChatGPT und Claude autorisieren Sie also getrennt.

OAuth-Parameter für eigene Clients

```
authorization_endpoint:  https://mcp.ailon.io/authorize/
scope:                   ailon:mcp
resource:                https://mcp.ailon.io
code_challenge_method:   S256   # PKCE erforderlich
```

Gängige Clients wie Claude, ChatGPT oder Cursor bringen den Ablauf mit und registrieren sich selbst — dort genügt die Server-URL.

## Organisationen & Rechte

Jeder Benutzer kann eine eigene Organisation gründen und darin Organisationsprojekte anlegen. Innerhalb einer bestehenden Organisation vergibt die Administratorin die Rechte individuell — wer also keine Organisationsprojekte anlegen kann, wendet sich an sie. Wer das ist, steht im Dashboard unter [Organisation → Übersicht](https://dashboard.ailon.io/dashboard/organisation/overview).

Projekte ohne `organisation_id` sind privat und nur für den anlegenden Benutzer sichtbar — über beide Zugänge gleichermaßen.

## Kostenlose Nutzung in Beispielprojekten gilt für beide Zugänge

Projekte mit dem Feld `"public": true` sind Beispielprojekte (im Dashboard: Demo-Projekte). Über die REST-API finden Sie sie mit `GET /projects/?public=true`, über MCP mit `list_projects`.

**Kostenlos:** Alle Anfragen an Zielgruppen in Beispielprojekten sind gebührenfrei — auch Insight-Daten (`/insights/{id}/data/`) und Zielgruppen-Zusammenfassungen (`.../summary/`), unabhängig vom angezeigten `credit_cost`.

**Ausnahme:** In Beispielprojekten lassen sich keine neuen Zielgruppen anlegen. Das betrifft `POST /projects/{project_id}/generate_audience/` ebenso wie das MCP-Tool `generate_audience`. Die Projekte sind sichtbar und lesbar, aber schreibgeschützt.

Für Einstieg und Experimente mit Insights empfiehlt sich daher ein Beispielprojekt mit bereits berechneten Zielgruppen (Feld `calculated_audience_ids`). In eigenen Projekten (`public: false`) können credit-pflichtige Abrufe das Guthaben belasten — Details dazu im nächsten Abschnitt.

## Credits & Abrechnung gilt für beide Zugänge

Gilt ausschließlich für Zielgruppen in eigenen Projekten — Beispielprojekte sind immer kostenlos. Abgerechnet wird der Datenabruf, nicht der Zugangsweg: Über MCP entstehen keine zusätzlichen Kosten.

- Credits kosten der Abruf von Insight-Daten (`GET /insights/{id}/data/` bzw. `get_insight_data`) sowie die KI-generierte Zielgruppen-Zusammenfassung (`.../summary/`, ein Credit). Projekte anlegen, Zielgruppen erzeugen, Merkmale suchen und alle Listenabrufe sind kostenfrei.
- Abgebucht wird ausschließlich bei erfolgreicher Antwort (`status: SUCCESS`) — Zwischenstände (`CALCULATING`) sind kostenlos.
- Berechnet wird **je Zielgruppe und je Aufruf**. Ein Vergleich von vier Zielgruppen über dieselbe Feature-Kategorie kostet das Vierfache.
- Das Guthaben gehört dem zugreifenden Benutzer und ist über beide Zugänge dasselbe. Standardmäßig darf es nicht unter null fallen.
- Ein von AIlon festgelegtes Überziehungslimit (`min_balance`) ist über `GET /usage/credit-limit/` einsehbar. Reicht das Guthaben nicht aus, antwortet die API mit `402 Payment Required`.

### Preisstufen

Die rund 5.100 Merkmale sind in 17 **Feature-Kategorien** gebündelt, die sich in drei Preisstufen aufteilen. Die Stufe ist am Präfix des Namens erkennbar.

| Stufe | Credits | Enthalten |
| --- | --- | --- |
| **Basic** | 1 | Basissoziodemografie: Alter, Geschlecht, Bildung, Kinder, Bundesland, Haushaltsnetto |
| **Extended** | 3 | 14 Kategorien, u. a. Kaufverhalten, Lebensmittel, Reisen, Mode, Beruf, Mobilität, Technik |
| **Plus** | 10 | Marken (rund 2.060 Merkmale) und Mediennutzung |

**Zur Begrifflichkeit:** Feature-Kategorien heißen in der REST-API historisch *Insights* — der Endpunkt lautet weiterhin `/insights/`, und die IDs sind in beiden Zugängen identisch. Gemeint ist dasselbe: ein thematisches Bündel von Merkmalen. Ein einzelnes Merkmal darin, etwa „Grillen“, heißt *Feature* und kann zu mehreren Kategorien gehören.

Die tatsächliche Abbuchung steht nach dem Aufruf in der Antwort: bei MCP im Feld `billing` mit `credits_charged`, `balance_before` und `balance_after`. Vorab prüfen lässt sich der Preis über `GET /insights/{id}/credit-cost/` bzw. über den `credit_cost` aus `list_feature_categories`.

```
curl -s -H "Authorization: Bearer IHR_API_KEY" \
  https://dashboard.ailon.io/public-api/v1/usage/
```

Kopieren

## Datenschutz & Betrieb

| Thema | Angabe |
| --- | --- |
| **Serverstandort** | Frankfurt am Main, Deutschland |
| **Vertragsgrundlage** | [Allgemeine Geschäftsbedingungen](https://ailon.io/agb?hsLang=de) |
| **Protokollierung** | Alle API-Aufrufe werden bei AIlon protokolliert und sind über `GET /usage/requests/` einsehbar |
| **Ratenbegrenzung** | keine; begrenzend wirkt allein das Credit-Guthaben |

### Was beim MCP-Zugriff wohin geht

Beim Zugriff über einen KI-Client verarbeitet dessen Anbieter zwangsläufig die Konversation: Ihre Fragen, die Antworten des Modells sowie die Daten, die der MCP-Server zurückliefert und die das Modell für seine Antwort benötigt. Welche Aufrufe der Agent auslöst, ist im Client sichtbar. Für welche Zwecke der Anbieter diese Inhalte verwendet und wie lange er sie speichert, richtet sich nach dessen Bedingungen und Ihren dortigen Einstellungen — darauf hat AIlon keinen Einfluss.

Die REST-API kennt diesen Weg nicht: Dort fließen Daten ausschließlich zwischen Ihrem System und AIlon.

### Auftragsverarbeitung

Vertragliche Regelungen zur Datenverarbeitung stimmen wir individuell ab. Anfragen richten Sie an [kontakt@erason.de](mailto:kontakt@erason.de).

## Referenz für KI-Agenten

Kompakte, maschinenlesbare Orientierung für LLM-gestützte Tools. Eine reine Textversion dieser Seite steht zusätzlich unter [/llms.txt](https://ailon.io/llms.txt?hsLang=de) bereit.

**Unterstützt Ihr Client MCP, nutzen Sie den MCP-Server.** Er ist der vorgesehene Weg für Agenten: Die Tools sind beschrieben, die Abläufe über Playbooks hinterlegt, und der Credit-Verbrauch wird bei jedem Abruf ausgewiesen. Server-URL `https://mcp.ailon.io` → [zur Einrichtung](https://ailon.io/integration-dokumentation#mcp).

Nur wenn kein MCP-Support vorhanden ist — etwa bei reinem Function-Calling gegen eine eigene Toolchain oder bei Browser-Zugriff — folgen Sie dem REST-Ablauf darunter.

### MCP-Kurzprofil

```
server_url:  https://mcp.ailon.io
transport:   Remote MCP über HTTPS
auth:        OAuth 2 mit PKCE · scope ailon:mcp · Freigabe je Client
tools:       whoami · list_projects · list_audiences · create_project · generate_audience
             list_feature_categories · list_features_of_category · search_features
             get_insight_data · get_playbook
free_tier:   Projekte mit "public": true → Abrufe kostenlos, kein Anlegen möglich
credits:     nur get_insight_data; je Zielgruppe und je Aufruf; Verbrauch steht
             in der Antwort unter billing

# Empfohlener Ablauf für Agenten:
get_playbook          # passenden Arbeitsablauf laden
list_projects         # Kontext ermitteln
search_features       # reale Merkmale statt geratener Namen verwenden
generate_audience     # Zielgruppe anlegen und berechnen lassen
get_insight_data      # Kennwerte für bis zu 20 Zielgruppen vergleichen
```

### REST-Kurzprofil (Fallback)

```
base_url:      https://dashboard.ailon.io/public-api/v1/
auth:          Header Authorization: Bearer <ailpk_...>  # bei allen Endpunkten außer /health/
format:        application/json
no_auth_endpoint: GET /health/
free_tier:      Zielgruppen in Projekten mit "public": true → alle Insight-/Summary-Anfragen kostenlos
pagination:     Query-Parameter limit + offset; Antwort enthält items, count, limit, offset
errors:         401 ungültiger Key · 402 zu wenig Credits · 403 kein Zugriff/Beispielprojekt read-only
              404 nicht gefunden · 503 Zielgruppe wird noch berechnet

# Empfohlener Ablauf:
GET  /health/                                        # Erreichbarkeit prüfen, kein Auth nötig
GET  /whoami/                                         # Key validieren
GET  /projects/?public=true                           # kostenloses Beispielprojekt finden
GET  /projects/{project_id}/audiences/                # berechnete audience_id ermitteln
GET  /insights/                                        # insight_id + credit_cost ermitteln
GET  /insights/{insight_id}/data/?audience_id=...     # Analyse-Daten abrufen; ggf. bei status=CALCULATING erneut abfragen
```

## Schnellstart REST API

Sechs Aufrufe genügen, um vom leeren Terminal zu echten Insight-Daten zu kommen. Alle Beispiele nutzen ein **Beispielprojekt** (`public: true`) — dort sind Insight-Anfragen unabhängig vom angezeigten `credit_cost` immer kostenlos.

1. **API erreichbar?** `GET /health/` beantwortet ohne Authentifizierung, ob die API läuft und welche Version aktiv ist.
2. **API-Key gültig?** `GET /whoami/` bestätigt, welchem Benutzer und welcher Organisation der Key gehört.
3. **Beispielprojekt wählen.** `GET /projects/?public=true` liefert Projekte, an denen Sie kostenlos experimentieren können. Merken Sie sich eine `id` sowie eine ID aus `calculated_audience_ids`.
4. **Zielgruppe prüfen.** `GET /projects/{project_id}/audiences/` zeigt die berechneten Zielgruppen des Projekts inklusive Segmenten.
5. **Feature-Kategorie auswählen.** `GET /insights/` listet alle verfügbaren Kategorien mit `id`, `display_name` und `credit_cost`.
6. **Daten abrufen.** `GET /insights/{insight_id}/data/?audience_id={audience_id}` liefert die eigentlichen Analyse-Daten.

Anfragemuster (gilt für alle Endpunkte)

Jeder Endpunkt außer `/health/` erwartet denselben Authorization-Header. Ersetzen Sie für andere Endpunkte lediglich Methode, Pfad und ggf. den JSON-Body.

```
# cURL
curl -s -H "Authorization: Bearer IHR_API_KEY" \
  https://dashboard.ailon.io/public-api/v1/whoami/
```

Kopieren

```
# Python (requests)
import requests

response = requests.get(
    "https://dashboard.ailon.io/public-api/v1/whoami/",
    headers={"Authorization": "Bearer IHR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

Kopieren

```
// JavaScript (fetch)
const response = await fetch("https://dashboard.ailon.io/public-api/v1/whoami/", {
  headers: { Authorization: "Bearer IHR_API_KEY" },
});
console.log(await response.json());
```

Kopieren

**POST-Anfragen** senden zusätzlich `Content-Type: application/json` und einen JSON-Body per `-d` (cURL), `json=` (Python) bzw. `body: JSON.stringify(...)` (JavaScript). Der jeweilige Body ist bei den einzelnen Endpunkten dokumentiert.

## Endpunkt-Übersicht REST API

| Methode | Pfad | Zweck | Auth | Credits |
| --- | --- | --- | --- | --- |
| GET | `/health/` | Erreichbarkeit & API-Version | Nein | — |
| GET | `/whoami/` | Key-Identität prüfen | Ja | — |
| GET | `/projects/` | Sichtbare Projekte listen | Ja | — |
| POST | `/projects/` | Projekt anlegen | Ja | — |
| GET | `/projects/{id}/` | Ein Projekt abrufen | Ja | — |
| POST | `/projects/{id}/generate_audience/` | Zielgruppe aus Freitext erzeugen | Ja | Nicht in Beispielprojekten |
| GET | `/projects/{id}/audiences/` | Zielgruppen eines Projekts listen | Ja | — |
| GET | `/projects/{id}/audiences/{aid}/` | Eine Zielgruppe abrufen | Ja | — |
| GET | `/projects/{id}/audiences/{aid}/potential/` | Zielgruppengröße (relativ/absolut) | Ja | — |
| GET | `/projects/{id}/audiences/{aid}/summary/` | KI-generierte Zusammenfassung | Ja | 1 Credit · frei in Beispielprojekten |
| GET | `/insights/` | Feature-Kategorien listen | Ja | — |
| GET | `/insights/{id}/data/` | Insight-Daten für Zielgruppe | Ja | 1 / 3 / 10 · frei in Beispielprojekten |
| GET | `/insights/{id}/credit-cost/` | Kosten vorab prüfen | Ja | — |
| GET | `/insights/{id}/features/` | Merkmale einer Kategorie listen | Ja | — |
| GET | `/insights/{id}/features/{fid}/` | Ein Merkmal im Detail | Ja | — |
| GET | `/usage/` | Nutzungs-Zusammenfassung | Ja | — |
| GET | `/usage/credit-limit/` | Guthaben & Überziehungslimit | Ja | — |
| GET | `/usage/requests/` | Anfragen-Protokoll | Ja | — |
| GET | `/usage/ledger/` | Credit-Buchungen | Ja | — |
| GET | `/usage/keys/` | Eigene API-Keys listen | Ja | — |

## Pagination REST API

Listen-Endpunkte (`/projects/`, `/projects/{id}/audiences/`, `/usage/requests/`, `/usage/ledger/`) akzeptieren `limit` und `offset` und antworten in diesem Format:

```
{
  "items": [ … ],
  "count": 250,
  "limit": 100,
  "offset": 0
}
```

Weitere Seiten laden: `offset` so lange erhöhen, bis `offset + len(items) >= count`.

## Erste Schritte

GET/health/Kein Auth nötig

Prüft, ob die API erreichbar ist und welche Version aktuell aktiv ist. Der einzige Endpunkt ohne Authentifizierung — ideal für einen schnellen Erreichbarkeitscheck.

Beispielantwort

```
{ "status": "ok", "api_version": "v1" }
```

GET/whoami/Auth erforderlich

Bestätigt, dass der API-Key gültig ist, und zeigt, welchem Benutzer er gehört. Empfohlen als erster authentifizierter Aufruf.

Beispielantwort

```
{
  "user_id": 42,
  "username": "max.mustermann",
  "organisation_id": 7,
  "organisation_name": "Beispiel GmbH",
  "api_key_name": "Produktion",
  "api_key_prefix": "ailpk_abc123"
}
```

## Projekte & Zielgruppen

Projekte enthalten Zielgruppen (Audiences) und deren Segmente. Norm-Zielgruppen werden in den Listen nicht mitgeliefert.

GET/projects/Auth erforderlich

Listet alle Projekte, die der API-Key-Benutzer im Dashboard sehen darf — inklusive organisationsweiter Projekte und Projekte mit eingeschränktem Zugriff, in denen der Benutzer Mitglied ist.

| Parameter | In | Typ | Beschreibung |
| --- | --- | --- | --- |
| `public` | query | boolean | `true` = nur Beispielprojekte, `false` = nur eigene/Organisationsprojekte, weglassen = alle sichtbaren |
| `limit` | query | integer | Standard 100, max. 1000 |
| `offset` | query | integer | Standard 0 |

```
curl -s -H "Authorization: Bearer IHR_API_KEY" \
  "https://dashboard.ailon.io/public-api/v1/projects/?public=true&limit=10"
```

Kopieren

POST/projects/Auth erforderlich

Legt ein neues Projekt an: privat, wenn `organisation_id` weggelassen wird oder `null` ist, sonst organisationsweit für die passende Organisation.

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `name` | string (1–100 Zeichen) | Ja | Projektname |
| `description` | string / null | Nein | Optionale Beschreibung |
| `organisation_id` | integer / null | Nein | Ziel-Organisation; weglassen = privates Projekt |

```
curl -s -X POST -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sommerkampagne 2026", "description": "Neuprodukt-Launch"}' \
  https://dashboard.ailon.io/public-api/v1/projects/
```

Kopieren

GET/projects/{project\_id}/Auth erforderlich

Liefert ein einzelnes Projekt inklusive der IDs seiner Top-Level-Zielgruppen.

| Parameter | In | Typ |
| --- | --- | --- |
| `project_id` | path | integer |

POST/projects/{project\_id}/generate\_audience/Auth erforderlichNicht in Beispielprojekten

Erzeugt eine Zielgruppe per natürlicher Sprache: legt sie im Projekt an, lässt den KI-Recommender über den Prompt laufen, übernimmt die generierte Definition und startet die Dashboard-Berechnung. Erfordert Bearbeitungsrecht am Projekt und funktioniert **nicht** für Beispielprojekte (`public: true`). Die Zielgruppe wird sofort mit Status `Wird berechnet.` zurückgegeben, während Generierung und Berechnung asynchron laufen.

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `name` | string (1–100 Zeichen) | Ja | Name der Zielgruppe |
| `prompt` | string | Ja | Freitext-Beschreibung, aus der die Definition generiert wird |

```
curl -s -X POST -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Tech-affine Millennials", "prompt": "25-40 Jahre, hohe Online-Affinität"}' \
  https://dashboard.ailon.io/public-api/v1/projects/PROJECT_ID/generate_audience/
```

Kopieren

Status per `GET /projects/{project_id}/audiences/{audience_id}/` pollen, bis `status` den Wert `Berechnet` annimmt.

GET/projects/{project\_id}/audiences/Auth erforderlich

Listet die Top-Level-Zielgruppen eines Projekts inklusive ihrer Segmente. Norm-Zielgruppen sind ausgeschlossen.

| Parameter | In | Typ | Beschreibung |
| --- | --- | --- | --- |
| `project_id` | path | integer | — |
| `limit` | query | integer | Standard 100, max. 1000 |
| `offset` | query | integer | Standard 0 |

GET/projects/{project\_id}/audiences/{audience\_id}/Auth erforderlich

Liefert Metadaten für eine einzelne Zielgruppe innerhalb des angegebenen Projekts — u. a. den aktuellen `status`, hilfreich beim Polling nach `generate_audience`.

GET/projects/{project\_id}/audiences/{audience\_id}/potential/Auth erforderlich

Gibt zurück, wie groß die Zielgruppe relativ zum Projekt-Universum ist (`potential_relative`, Wert zwischen 0 und 1) sowie in absoluten Zahlen (`potential_absolute`).

```
{ "potential_relative": 0.184, "potential_absolute": 1284000 }
```

GET/projects/{project\_id}/audiences/{audience\_id}/summary/Auth erforderlich1 Creditfrei in Beispielprojekten

Gibt die KI-generierte Überblicks-Zusammenfassung einer Zielgruppe als Liste von Absätzen zurück. Kostet bei Erfolg ein Credit — in Beispielprojekten kostenlos. Die Zielgruppe muss vollständig berechnet sein, sonst schlägt die Anfrage fehl.

```
[
  { "type": "paragraph", "data": "Diese Zielgruppe zeichnet sich durch …" }
]
```

## Insights = Feature-Kategorien

Insights sind thematische Bündel von Merkmalen (z. B. Soziodemografie, Kaufverhalten, Marken), die auf eine berechnete Zielgruppe angewendet werden. Über MCP heißen sie *Feature-Kategorien*; die IDs sind dieselben.

GET/insights/Auth erforderlich

Listet jede für die aktuelle API-Version veröffentlichte Feature-Kategorie, inklusive der Credits, die bei erfolgreicher Datenabfrage berechnet werden.

```
[
  { "id": 4093, "display_name": "Basic | Soziodemografie",
    "description": "Geschlecht, Bildung, Anzahl Kinder, Bundesländer, Haushaltsnetto, …",
    "credit_cost": "1.00" },
  { "id": 4258, "display_name": "Extended | Kaufverhalten, Konsumpräferenzen und Einkaufsorte",
    "description": "Online-Shopping, Preisbewusstsein: Lebensmittel, Kaufabsicht: Smartphone, …",
    "credit_cost": "3.00" },
  { "id": 4193, "display_name": "Plus | Marken",
    "description": "Volkswagen, Apple, Kneipp, JYSK, Fritz-Cola, Miele, New Balance, …",
    "credit_cost": "10.00" }
]
```

GET/insights/{insight\_id}/data/Auth erforderlichfrei in Beispielprojekten

Berechnet oder liefert zwischengespeicherte Insight-Daten für die angegebene Zielgruppe. Credits werden vor der Berechnung reserviert und nur bei `status: SUCCESS` abgebucht. Zielgruppen in Beispielprojekten werden nie belastet.

| Parameter | In | Typ | Pflicht |
| --- | --- | --- | --- |
| `insight_id` | path | integer | Ja |
| `audience_id` | query | integer | Ja |

Statuswerte

| Status | Bedeutung |
| --- | --- |
| `SUCCESS` | Daten stehen in `data`; ggf. Credits abgebucht |
| `CALCULATING` | Noch in Berechnung — später erneut anfragen, kostenlos |
| `ERROR` | Fehlgeschlagen — Details in `error` und `error_code` |

```
curl -s -H "Authorization: Bearer IHR_API_KEY" \
  "https://dashboard.ailon.io/public-api/v1/insights/INSIGHT_ID/data/?audience_id=AUDIENCE_ID"
```

Kopieren

Beispielantwort (Feature mit Optionen, z. B. Altersgruppen)

```
{
  "insight_id": 4093, "audience_id": 55, "status": "SUCCESS", "error": null, "error_code": null,
  "data": [
    {
      "feature": { "id": 3, "display_name": "Alter" },
      "options": [
        { "option": { "id": 31, "display_name": "25-34" },
          "index_value": 142.0, "mean_pop": 0.18, "mean_audience": 0.26, "abs_audience": 331000 }
      ]
    }
  ]
}
```

GET/insights/{insight\_id}/credit-cost/Auth erforderlich

Gibt zurück, wie viele Credits eine erfolgreiche Insight-Datenabfrage für diese Zielgruppe kosten würde — sinnvoll, um Kosten vor der eigentlichen Abfrage zu prüfen. Für Zielgruppen in Beispielprojekten immer `0`.

| Parameter | In | Typ | Pflicht |
| --- | --- | --- | --- |
| `insight_id` | path | integer | Ja |
| `audience_id` | query | integer | Ja |

GET/insights/{insight\_id}/features/Auth erforderlich

Listet die demografischen oder verhaltensbezogenen Merkmale, aus denen eine Feature-Kategorie besteht, inklusive wählbarer Optionen pro Merkmal.

GET/insights/{insight\_id}/features/{feature\_id}/Auth erforderlich

Liefert die vollständigen Metadaten für ein einzelnes Merkmal, inklusive Beschreibung und wählbaren Optionen.

## Nutzung & Abrechnung

GET/usage/Auth erforderlich

Aggregiertes Guthaben und Anfrage-Statistiken für ein gleitendes Zeitfenster.

| Parameter | In | Typ | Beschreibung |
| --- | --- | --- | --- |
| `days` | query | integer | Standard 30, zwischen 1 und 365 |

GET/usage/credit-limit/Auth erforderlich

Aktuelles Guthaben und konfiguriertes Mindestguthaben (Überziehungslimit). Das Mindestguthaben wird von AIlon verwaltet und lässt sich nicht per API ändern.

GET/usage/requests/Auth erforderlich

Paginiertes Protokoll aller API-Anfragen inklusive Statuscodes, abgebuchten Credits und Fehlercodes fehlgeschlagener Aufrufe.

| Parameter | In | Typ | Beschreibung |
| --- | --- | --- | --- |
| `limit` | query | integer | Standard 50, max. 200 |
| `offset` | query | integer | Standard 0 |

GET/usage/ledger/Auth erforderlich

Paginierte Credit-Buchungen: Aufladungen, Abbuchungen und Anpassungen. Einträge verweisen bei Bedarf auf die auslösende Anfrage.

| Parameter | In | Typ | Beschreibung |
| --- | --- | --- | --- |
| `limit` | query | integer | Standard 50, max. 200 |
| `offset` | query | integer | Standard 0 |

GET/usage/keys/Auth erforderlich

Metadaten zu jedem API-Key des authentifizierten Benutzers. Geheime Werte werden nie zurückgegeben, nur der öffentliche Präfix.

## MCP-Server

 AIlon lässt sich direkt in gängigen KI-Clients nutzen. Für Claude und ChatGPT stehen offizielle AIlon-Plugins zur Verfügung. Diese können direkt installiert und anschließend mit dem eigenen AIlon-Account verbunden werden. Für weitere Clients wie Cursor, VS Code, n8n oder eigene Agents steht die AIlon MCP-Schnittstelle zur Verfügung.

 Über AIlon kann der Agent unter anderem Zielgruppen finden, neue Zielgruppen anlegen und berechnen lassen, Merkmale durchsuchen und Kennwerte für bis zu 20 Zielgruppen vergleichen.

| Merkmal | Angabe |
| --- | --- |
| **Claude** | Direkte Integration über das offizielle [AIlon-Plugin](https://claude.ai/directory/ailon) |
| **ChatGPT** | Direkte Integration über das offizielle [AIlon-Plugin](https://chatgpt.com/plugins/plugin_asdk_app_6a846c59181481918408490636fa6d47) |
| **Weitere Clients** | Anbindung über die AIlon MCP-Schnittstelle |
| **Server-URL** | `https://mcp.ailon.io` |
| **Transport** | Remote MCP über HTTPS |
| **Authentifizierung** | OAuth 2 mit PKCE, siehe [Authentifizierung](https://ailon.io/integration-dokumentation#auth) |
| **Umfang** | 10 Tools, lesend und schreibend |
| **Clients** | Claude, ChatGPT, Cursor, VS Code, n8n und eigene Agents |
| **Lizenz** | API-/MCP-Lizenz, siehe [Lizenzen](https://ailon.io/integration-dokumentation#lizenzen) |

## Einrichtung Plugins & MCP-Server

 Für Claude und ChatGPT ist die Einrichtung besonders einfach. Installieren Sie das jeweilige AIlon-Plugin, melden Sie sich einmal mit Ihrem AIlon-Account an und starten Sie direkt mit der Nutzung. Die Einrichtung dauert in der Regel nur etwa eine Minute.

1. **In AIlon registrieren.** Registrieren Sie sich bei AIlon unter [https://ailon.io/register](https://ailon.io/register?hsLang=de).
2. **Claude oder ChatGPT verbinden.** Für Claude verwenden Sie das [offizielle AIlon-Plugin](https://claude.ai/directory/ailon). Für ChatGPT verwenden Sie das [offizielle AIlon-Plugin](https://chatgpt.com/plugins/plugin_asdk_app_6a846c59181481918408490636fa6d47). Installieren Sie das Plugin und starten Sie anschließend die Anmeldung bei AIlon.
3. **Andere Clients über MCP verbinden.** Für Cursor, VS Code, n8n oder eigene Agents fügen Sie einen Remote-MCP-Server hinzu. Verwenden Sie als Server-URL `https://mcp.ailon.io`. Als Namen empfehlen wir `AIlon`. Je nach Client heißt der entsprechende Menüpunkt zum Beispiel „Connector“, „MCP Server“ oder `mcp.json`.
4. **Autorisieren.** Der Client öffnet die AIlon-Anmeldung im Browser. Melden Sie sich mit Ihrem AIlon-Account an, bestätigen Sie die Berechtigung *Access AIlon MCP tools* und klicken Sie auf *Authorize*. Ein API-Key muss nicht eingetragen werden.
5. **Verbindung prüfen.** Fragen Sie den Agent nach Benutzer und Guthaben. Der Agent kann dafür `whoami` aufrufen und Benutzer, Organisation und Credit-Stand zurückgeben. Wenn diese Informationen erscheinen, ist die Verbindung erfolgreich eingerichtet.
6. **Ersten kostenfreien Test starten.** Beispielprojekte kosten keine Credits und eignen sich für den ersten Test.

Beispielprompt Zeig mir die öffentlichen Beispielprojekte von AIlon, wähl eine Zielgruppe aus und beschreib mir ihre Mediennutzung.

## Clients verbinden Stand: September 2026

 AIlon lässt sich direkt mit verschiedenen KI-Clients verbinden. Für Claude und ChatGPT stehen inzwischen offizielle AIlon-Plugins zur Verfügung. Die Einrichtung dauert in der Regel nur etwa eine Minute: Plugin installieren, mit dem eigenen AIlon-Account authentifizieren und anschließend direkt im Chat verwenden.

### Claude mit AIlon verbinden

 Für Claude steht AIlon als offizieller Connector im Claude-Verzeichnis zur Verfügung.

1. **AIlon Plugin im Claude Marketplace öffnen.** Das [AIlon-Plugin im Claude-Verzeichnis](https://claude.ai/directory/ailon) öffnen.
2. **Plugin installieren.** AIlon zum eigenen Claude-Account hinzufügen.
3. **Mit AIlon anmelden.** Bei der ersten Verbindung öffnet sich die AIlon-Anmeldung. Mit dem eigenen AIlon-Account anmelden und den Zugriff bestätigen.
4. **AIlon verwenden.** Danach kann AIlon direkt in Claude verwendet werden. Falls der Connector in einem Chat nicht aktiv ist, kann er über das Werkzeugmenü ausgewählt werden.

**Einrichtung in etwa einer Minute:** Plugin installieren, einmal mit AIlon authentifizieren und direkt loslegen. Der Connector kann anschließend mit demselben Claude-Account in den unterstützten Claude-Produkten verwendet werden.

Direkt zum AIlon-Plugin

[AIlon für Claude installieren](https://claude.ai/directory/ailon)

Herstellerdokumentation

[Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

### ChatGPT mit AIlon verbinden

 Auch für ChatGPT steht AIlon inzwischen als offizielles Plugin zur Verfügung.

1. **AIlon Plugin im ChatGPT Marketplace öffnen.** Das [AIlon-Plugin in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a846c59181481918408490636fa6d47) öffnen.
2. **Plugin installieren.** AIlon zum eigenen ChatGPT-Account hinzufügen.
3. **Mit AIlon anmelden.** Bei der ersten Verbindung öffnet sich die AIlon-Anmeldung. Mit dem eigenen AIlon-Account anmelden und den Zugriff bestätigen.
4. **AIlon verwenden.** Anschließend kann das AIlon-Plugin direkt in ChatGPT ausgewählt und im Chat verwendet werden.

**Einrichtung in etwa einer Minute:** Plugin installieren, einmal mit AIlon authentifizieren und direkt loslegen. Für eine gezielte Nutzung kann AIlon im Chat ausgewählt oder direkt im Prompt angesprochen werden, zum Beispiel: „Nutze AIlon, um diese Zielgruppe zu analysieren.“

Direkt zum AIlon-Plugin

[AIlon für ChatGPT installieren](https://chatgpt.com/plugins/plugin_asdk_app_6a846c59181481918408490636fa6d47)

Herstellerdokumentation

[Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)

### GitHub Copilot mit AIlon verbinden

 Copilot spricht MCP im **Agent-Modus**. Die Konfiguration liegt in einer JSON-Datei, entweder arbeitsbereichsweit in `.vscode/mcp.json` oder in der persönlichen Konfiguration über die Befehlspalette unter *MCP: Open User Configuration*. Für Remote-Server mit OAuth wird VS Code 1.101 oder neuer benötigt.

```
// .vscode/mcp.json
{
  "servers": {
    "ailon": {
      "type": "http",
      "url": "https://mcp.ailon.io"
    }
  }
}
```

Kopieren

1. **Konfiguration speichern.** Über dem Servereintrag erscheint eine *Start*-Schaltfläche. Ein Klick startet den Server und öffnet die Anmeldung bei AIlon im Browser.
2. **Agent-Modus wählen.** Im Copilot-Chat oben von *Ask* auf *Agent* umschalten.
3. **Tools prüfen.** Über das Werkzeugsymbol im Chatfenster erscheint die Liste der verbundenen Server. Dort sollten die AIlon-Tools erscheinen.
4. **Aufrufe bestätigen.** Abhängig von den Copilot-Einstellungen kann vor Tool-Aufrufen eine Bestätigung notwendig sein.

**Copilot Business und Enterprise:** Dort kann die Nutzung eigener MCP-Server durch Organisationsrichtlinien eingeschränkt sein. Die Richtlinie für MCP-Server muss gegebenenfalls auf Organisations- oder Enterprise-Ebene freigegeben werden. Dieselbe `mcp.json` kann auch in weiteren unterstützten Entwicklungsumgebungen verwendet werden.

Herstellerdokumentation

[Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers) · [Enhancing GitHub Copilot agent mode with MCP](https://docs.github.com/en/copilot/tutorials/enhance-agent-mode-with-mcp)

### Weitere Clients mit AIlon verbinden

 AIlon kann grundsätzlich mit jedem Client verbunden werden, der Remote-MCP-Server über HTTPS unterstützt. Dazu gehören zum Beispiel Cursor, n8n und eigene Agents auf Basis der MCP-SDKs. Für die manuelle Verbindung wird die Server-URL `https://mcp.ailon.io` verwendet. Die Anmeldung erfolgt über OAuth, siehe [Authentifizierung](https://ailon.io/integration-dokumentation#auth).

## Tool-Referenz MCP-Server

Alle Tools stehen nach dem Verbinden automatisch zur Verfügung. Der Agent wählt sie selbst aus — Sie müssen sie nicht kennen, um zu arbeiten. Die Übersicht hilft, wenn Sie den MCP-Server in ein eigenes Produkt einbauen.

| Tool | Was es tut | Zugriff | Credits |
| --- | --- | --- | --- |
| `whoami` | Benutzer, Organisation und Credit-Stand der Session | lesend | keine |
| `list_projects` | Projekte listen, optional nur Beispielprojekte | lesend | keine |
| `list_audiences` | Zielgruppen mit berechneter Definition und Reichweite, global oder gefiltert | lesend | keine |
| `list_feature_categories` | verfügbare Kategorien inklusive `credit_cost` | lesend | keine |
| `list_features_of_category` | alle Merkmale einer Kategorie | lesend | keine |
| `search_features` | semantische Suche über alle Merkmale, kategorieübergreifend | lesend | keine |
| `get_insight_data` | Kennwerte für 1–20 Zielgruppen im Vergleich | lesend | 1 / 3 / 10 je Zielgruppe |
| `get_playbook` | hinterlegte Arbeitsabläufe; ohne Argument die Liste aller Playbooks | lesend | keine |
| `create_project` | Projekt anlegen, optional mit mehreren Zielgruppen | **schreibend** | keine |
| `generate_audience` | Zielgruppe aus einem Prompt erzeugen und berechnen | **schreibend** | keine |

Von allen Tools kostet einzig `get_insight_data` Credits. Zielgruppen anlegen und berechnen zu lassen ist kostenfrei — bezahlt wird erst die Auswertung.

### Gut zu wissen

TOOLsort\_audience\_id ist Pflicht

`get_insight_data` liefert immer eine Vergleichsdarstellung und benötigt daher eine Zielgruppe, nach der sortiert wird — auch dann, wenn nur eine einzige Zielgruppe abgefragt wird.

TOOLZielgruppen entstehen aus echten Merkmalen

Bevor der Agent eine Zielgruppe anlegt, prüft er über `search_features`, welche Attribute es in AIlon tatsächlich gibt. Erfundene Merkmalsnamen würden sonst still zu einer Zielgruppe führen, die nicht dem entspricht, was gemeint war.

TOOLDie berechnete Definition ist die Wahrheit

Jede Zielgruppe trägt neben dem Prompt auch die finale, von AIlon berechnete Boolesche Definition. Lassen Sie sie sich ausgeben, um zu prüfen, was wirklich in der Zielgruppe steckt.

TOOLBerechnungen dauern

Das Anlegen mehrerer Zielgruppen kann bis zu einer Minute in Anspruch nehmen. Der Aufruf wartet, bis alles fertig gerechnet ist.

## Playbooks MCP-Server

Damit ein Agent Zielgruppen methodisch sauber modelliert statt zu raten, liefert der Server hinterlegte Arbeitsabläufe mit. `get_playbook` ohne Argument gibt die aktuelle Liste zurück.

| Playbook | Wann es greift |
| --- | --- |
| Projekt analysieren | Bestehende Zielgruppen erkunden und Insights ziehen |
| Zielgruppe aus vorhandenen Daten modellieren | Alter, Geschlecht, Persona oder Merkmale stehen bereits fest |
| Zielgruppen ohne Daten-Briefing entwickeln | Es liegt nur ein Geschäftsziel oder Produkt vor |
| Hilfe und Orientierung | Credits, Authentifizierung, Funktionsumfang |

BeispielpromptNutze das AIlon-Playbook für die Zielgruppenentwicklung ohne Daten-Briefing.

## Troubleshooting MCP-Server

| Symptom | Ursache und Lösung |
| --- | --- |
| Menüpunkt für eigene Connectoren fehlt | In Team- oder Enterprise-Workspaces muss die Administratorin eigene MCP-Server freigeben. Manche Clients bieten die Funktion zudem erst ab bestimmten Tarifen an. |
| Autorisierung schlägt fehl | Der Browser muss das AIlon-Anmeldefenster öffnen dürfen — Pop-up-Blocker prüfen, danach den Vorgang im Client erneut starten. |
| Falscher Benutzer verbunden | Der Dialog zeigt vor der Freigabe an, wer angemeldet ist. Bei mehreren AIlon-Konten zuerst im Browser abmelden, dann erneut autorisieren. |
| Verbindung steht, keine Tools sichtbar | Client neu starten und die Verbindung erneut öffnen. Manche Clients laden die Tool-Liste erst beim Start eines neuen Chats. |
| Kein Zugriff auf Organisationsprojekte | Die Rechte vergibt die Organisationsadministratorin, siehe [Organisationen & Rechte](https://ailon.io/integration-dokumentation#rollen). |
| Agent findet die Zielgruppe nicht | Zielgruppen sind an Projekte gebunden. Erst die Projektliste abfragen, dann gezielt filtern lassen. |
| Zielgruppe passt nicht zum Prompt | Berechnete Definition ausgeben lassen und mit den tatsächlich vorhandenen Merkmalen nachformulieren. |
| Nicht genug Credits | Kontostand mit `whoami` prüfen, Guthaben aufladen oder Beispielprojekte nutzen, siehe [Credits](https://ailon.io/integration-dokumentation#credits). |
| Anlegen im Beispielprojekt scheitert | Beispielprojekte sind schreibgeschützt, siehe [Beispielprojekte](https://ailon.io/integration-dokumentation#free-usage). |

## Tool ↔ Endpunkt

Wer prototypisch im Chat startet und später produktiv auf REST wechselt, findet hier den passenden Endpunkt — und umgekehrt.

| MCP-Tool | REST-Endpunkt |
| --- | --- |
| `whoami` | `GET /whoami/` |
| `list_projects` | `GET /projects/` |
| `list_audiences` | `GET /projects/{id}/audiences/` |
| `create_project` | `POST /projects/` |
| `generate_audience` | `POST /projects/{id}/generate_audience/` |
| `list_feature_categories` | `GET /insights/` |
| `list_features_of_category` | `GET /insights/{id}/features/` |
| `get_insight_data` | `GET /insights/{id}/data/` |
| `search_features` | kein Äquivalent — nur über MCP |
| `get_playbook` | kein Äquivalent — nur über MCP |
| kein Äquivalent — nur über REST | `/health/`, `.../potential/`, `.../summary/`, `/insights/{id}/credit-cost/`, `/usage/*` |

## Status- & Fehlercodes gilt für beide Zugänge

Zielgruppen-Status (Dashboard → API)

| Dashboard-Status | Bedeutung für die API |
| --- | --- |
| `Wird berechnet.` | Asynchrone Erzeugung oder Berechnung läuft |
| `Berechnet` / `Berechnet.` | Bereit für Insight-Abfragen |
| `Berechnung fehlgeschlagen` | Erzeugung oder Berechnung fehlgeschlagen |

HTTP-Fehlercodes

| HTTP | Beispiel error\_code | Bedeutung |
| --- | --- | --- |
| `401` | — | Ungültiger API-Key |
| `402` | `insufficient_credits` | Guthaben reicht nicht aus |
| `403` | `example_project_readonly`, `project_not_editable` | Beispielprojekt oder fehlende Berechtigung |
| `404` | `project_not_found` | Nicht sichtbar oder existiert nicht |
| `503` | `audience_calculating` | Zielgruppe wird noch berechnet |

Häufige Insight-error\_codes

| Code | Bedeutung |
| --- | --- |
| `audience_not_calculated` | Zielgruppe noch nicht berechnet |
| `audience_outdated` | Veraltete Definition |
| `segments_excluded` | Kategorie unterstützt keine Segmente |
| `calculation_failed` | Interne Berechnung fehlgeschlagen |

Fehlercodes aller Anfragen lassen sich zusätzlich über `GET /usage/requests/` nachvollziehen. Über MCP gelten dieselben Ursachen; wie ein Fehler im Chat erscheint, entscheidet der jeweilige Client.

## Datenmodelle gilt für beide Zugänge

Feldreferenz der wichtigsten Antwort- und Body-Schemas. Klappen Sie ein Modell auf, um alle Felder mit Typ und Beschreibung zu sehen.

ProjectSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `id` | integer | — |
| `name` | string | — |
| `description` | string / null | — |
| `public` | boolean | Beispielprojekt ja/nein; Insight-Anfragen dafür sind kostenlos, Zielgruppen können nicht hinzugefügt werden |
| `updated` | date-time | — |
| `audience_ids` | integer\[\] | IDs der Top-Level-Zielgruppen |
| `calculated_audience_ids` | integer\[\] | IDs der Top-Level-Zielgruppen mit Status „berechnet“ |
| `segments` | object | Segment-IDs gruppiert nach übergeordneter Zielgruppen-ID |

CreateProjectSchema Request-Body

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `name` | string (1–100) | Ja | Projektname |
| `description` | string / null | Nein | — |
| `organisation_id` | integer / null | Nein | Weglassen/`null` = privates Projekt |

AudienceSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `id` | integer | — |
| `name` | string | — |
| `description` | string / null | — |
| `status` | string / null | Siehe Tabelle „Zielgruppen-Status“ |
| `updated_at` | date-time / null | — |
| `segments` | AudienceSchema\[\] | Untergeordnete Zielgruppen (Segmente) |

GenerateAudienceSchema Request-Body

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `name` | string (1–100) | Ja | Name der Zielgruppe |
| `prompt` | string | Ja | Freitext, aus dem die Definition generiert wird |

PotentialSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `potential_relative` | number | Größe relativ zum Projekt-Universum (0–1) |
| `potential_absolute` | integer | Geschätzte Größe im Projekt-Universum |

AudienceSummaryParagraphSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `type` | string, konstant `"paragraph"` | — |
| `data` | string | Text des Absatzes |

InsightSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `id` | integer | Als `insight_id` in anderen Endpunkten verwenden; über MCP `feature_category_id` |
| `display_name` | string | — |
| `description` | string | Öffentliche Beschreibung |
| `credit_cost` | string | Credits pro erfolgreicher Datenabfrage und Zielgruppe |

InsightDataSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `insight_id` | integer | — |
| `audience_id` | integer | — |
| `status` | `SUCCESS` / `CALCULATING` / `ERROR` | Berechnungsstatus |
| `error` | string / null | Erklärung, wenn `status = ERROR` |
| `error_code` | string / null | Maschinenlesbarer Fehlercode |
| `data` | InsightFeatureDataSchema\[\] / object / null | Payload bei `SUCCESS`. Standard-Kategorien liefern eine Liste von Merkmalen mit verschachtelten `options`; abweichende liefern das rohe Widget-Objekt |

InsightFeatureDataSchema & InsightFeatureOptionDataSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `feature` | { id, display\_name } | Referenz auf das Merkmal |
| `option` | { id, display\_name } | Nur in `InsightFeatureOptionDataSchema`: Referenz auf die Wertoption |
| `index_value` | number / null | Über- (\>100) bzw. Unterrepräsentation (\<100) gegenüber der Bevölkerung |
| `mean_pop` | number / null | Mittelwert in der Gesamtbevölkerung; gesetzt, wenn das Merkmal keine Optionen hat |
| `mean_audience` | number / null | Mittelwert in der Zielgruppe (z. B. Durchschnittsalter) |
| `mean_audience_in_feature` | number / null | — |
| `abs_audience` | integer / null | Absolute Anzahl in der Zielgruppe |
| `effect_value` | number / null | — |
| `options` | InsightFeatureOptionDataSchema\[\] | Nur bei Merkmalen mit Wertbändern; pro Option dieselben Metrikfelder |

InsightCreditCostSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `insight_id` | integer | — |
| `audience_id` | integer | — |
| `credit_cost` | string | `0` für Zielgruppen in Beispielprojekten |

InsightFeatureSchema / InsightFeatureDetailSchema / InsightFeatureOptionSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `id` | integer | — |
| `display_name` | string / null | — |
| `display_name_category` | string / null | — |
| `description` | string | Nur im Detail-Schema |
| `logo_or_icon` | string / null | Nur im Detail-Schema |
| `options[].id` | integer | — |
| `options[].display_name` | string | — |
| `options[].lower_border` / `upper_border` | number / null | Grenzen des Wertbands |

UsageSummarySchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `balance` | string | Aktuelles Guthaben |
| `min_balance` | string | 0 deaktiviert Überziehung; negative Werte erlauben ein Minus bis zu diesem Limit |
| `period_days` | integer | Länge des Zusammenfassungs-Zeitfensters |
| `request_count` | integer | — |
| `credits_used` | string | Insgesamt abgebuchte Credits im Zeitfenster |
| `successful_requests` | integer | — |
| `failed_requests` | integer | — |

CreditLimitSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `balance` | string | — |
| `min_balance` | string | Von AIlon konfiguriertes Überziehungslimit |

RequestLogEntrySchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `request_id` | uuid | — |
| `api_key_prefix` | string / null | — |
| `method` | string | — |
| `path` | string | — |
| `status_code` | integer | — |
| `credits_charged` | string | — |
| `duration_ms` | integer / null | — |
| `error_code` | string | Leer bei Erfolg |
| `created_at` | date-time | — |

LedgerEntrySchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `id` | integer | — |
| `amount` | string | Positiv bei Aufladung, negativ bei Abbuchung |
| `balance_after` | string | — |
| `reason` | string | — |
| `note` | string | — |
| `request_id` | uuid / null | Auslösende Anfrage, falls zutreffend |
| `created_at` | date-time | — |

ApiKeySummarySchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `id` | integer | — |
| `name` | string | — |
| `prefix` | string | Öffentlicher Präfix, nicht geheim |
| `is_active` | boolean | — |
| `last_used_at` | date-time / null | — |
| `created_at` | date-time | — |

HealthResponseSchema / WhoAmIResponseSchema

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `status` | string | Immer `"ok"`, wenn erreichbar |
| `api_version` | string | Aktiver Versions-Slug, z. B. `v1` |
| `user_id` | integer | — |
| `username` | string | — |
| `organisation_id` | integer / null | — |
| `organisation_name` | string / null | — |
| `api_key_name` | string | Beim Erstellen des Keys vergebenes Label |
| `api_key_prefix` | string | Öffentlicher Teil des Keys vor dem Geheimteil |

## Fehlende Merkmale & eigene Daten

Findet sich für ein gewünschtes Merkmal keine Entsprechung in AIlon, lässt es sich zur Aufnahme vorschlagen. Über dasselbe Formular läuft auch der Wunsch, eigene Daten aus CRM, POS, Kampagnen oder Marktforschung einzubringen und mit den rund 5.100 AIlon-Merkmalen anzureichern — das geschieht über [AIlon SYNQ](https://ailon.io/synq?hsLang=de) in einem eigenen Onboarding und nicht über API oder MCP.

[Zum Formular für Merkmalswünsche und Datenintegration](https://share-eu1.hsforms.com/1iXpNGgIJSICrnniu5DQrqA2dx5ro)

Hintergrund zur Datengrundlage: [Die Datenquellen von AIlon im Detail](https://ailon.io/faq/die-datenquellen-von-ailon-im-detail?hsLang=de).

 AIlon Developer-Dokumentation · REST-Basis-URL `https://dashboard.ailon.io/public-api/v1/` · MCP-Server `https://mcp.ailon.io` · Textversion unter [/llms.txt](https://ailon.io/llms.txt?hsLang=de)

```json
{
  "@context" : "https://schema.org",
  "@type" : "TechArticle",
  "about" : [ {
    "@type" : "SoftwareApplication",
    "applicationCategory" : "DeveloperApplication",
    "name" : "AIlon Public API",
    "url" : "https://dashboard.ailon.io/public-api/v1/"
  }, {
    "@type" : "SoftwareApplication",
    "applicationCategory" : "DeveloperApplication",
    "name" : "AIlon MCP-Server",
    "url" : "https://mcp.ailon.io"
  } ],
  "description" : "Referenzdokumentation von AIlon: Projekte, Zielgruppen und Insight-Daten per REST-API abrufen oder per MCP-Server direkt in KI-Clients nutzen.",
  "headline" : "AIlon Developer-Dokumentation — Public API v1 und MCP-Server",
  "inLanguage" : "de",
  "publisher" : {
    "@type" : "Organization",
    "name" : "AIlon",
    "url" : "https://ailon.io"
  },
  "url" : "https://ailon.io/api-dokumentation"
}
```