Die API v2: KI-ready dank OpenAPI und Blueprints

Eine Software an einen KI-Assistenten oder ein Automatisierungstool anzubinden, scheitert selten am Protokoll. Es scheitert daran, dass das andere System nicht weiß, wie die Daten aussehen: Welche Felder gibt es, welche sind Pflicht, welcher Typ steckt dahinter, welche Werte sind erlaubt? Diese Lücke füllt man normalerweise mit handgeschriebener Dokumentation und Glue-Code — und pflegt beides bei jeder Änderung nach.

Die REST-API v2 von ameax geht den umgekehrten Weg: Sie beschreibt sich selbst. Eine OpenAPI-Dokumentation liefert alle Endpunkte und Felder maschinenlesbar, und für die pro Installation individuell konfigurierten Objekte und Kampagnen kommt das Schema live aus der API. Genau das macht sie KI-ready — und einfach in Tools wie n8n einzubinden.

Was heißt KI-ready bei einer Schnittstelle?

Eine KI-ready Schnittstelle ist eine, die ein Sprachmodell oder ein Agent benutzen kann, ohne dass ihm jemand vorher von Hand erklärt, wie sie funktioniert. Der Agent liest die Beschreibung der API selbst aus, versteht daraus die verfügbaren Endpunkte und Felder — und ruft sie korrekt auf.

Damit das gelingt, muss die Schnittstelle drei Dinge mitbringen: eine standardisierte, vorhersehbare Struktur; maschinenlesbare Feld-Metadaten mit Typ, Pflichtangabe und erlaubten Werten; und eine Möglichkeit, das Datenmodell zur Laufzeit abzufragen — auch dort, wo es sich pro Kunde unterscheidet. Die API v2 erfüllt alle drei.

OpenAPI: die Schnittstelle beschreibt sich selbst

Die API stellt ihre komplette Beschreibung als OpenAPI-Dokument (Version 3.0.3) bereit — im JSON- wie im YAML-Format. Diese Datei ist kein von Hand gepflegtes Dokument, das irgendwann veraltet, sondern wird direkt aus der Schnittstelle selbst erzeugt: Jedes Feld jeder Ressource trägt seinen Typ, sein Format, eine Beschreibung, ob es Pflicht ist und welche Werte es annehmen darf. Genau diese Angaben landen in der OpenAPI-Datei.

Der praktische Nutzen ist groß, weil OpenAPI ein verbreiteter Standard ist:

• KI-Assistenten laden die Datei und wissen sofort, welche Aktionen es gibt und wie ein gültiger Aufruf aussieht.
• Client-Bibliotheken für nahezu jede Programmiersprache lassen sich daraus generieren, statt sie zu schreiben.
• API-Werkzeuge wie Postman oder Insomnia importieren die Datei und bilden die gesamte Schnittstelle ab.

Die Dokumentation deckt die volle Breite der Anwendung ab — von Kunden, Ansprechpartnern und Kategorien über die Zeiterfassung bis zur Faktura mit Belegen, Positionen, Preisen und Abonnements.

Blueprints für Objekte und Kampagnen

Eine statische Dokumentation hat eine Grenze: Sie kann nur beschreiben, was in jeder Installation gleich ist. In ameax legen Sie aber eigene Objekte und Kampagnen mit frei konfigurierbaren Zusatzfeldern an — das Datenmodell sieht also bei jedem Kunden anders aus. Eine feste Beschreibung könnte diese individuellen Felder gar nicht kennen.

Dafür gibt es die Blueprint-Endpunkte. Sie liefern zur Laufzeit ein vollständiges, selbstbeschreibendes Schema Ihrer Objekte und Kampagnen — als standardisiertes JSON-Schema, mit allen Feldern, ihren Typen, erlaubten Werten, Pflichtangaben, Bezeichnungen und Beispielen. Für jeden konfigurierbaren Objekttyp ist der verfügbare Feldtyp-Katalog dabei ausgewiesen, vom Textfeld über Datum, Auswahl und Währung bis zur Kunden- oder Adressverknüpfung.

Daraus ergibt sich ein sauberes zweistufiges Bild:

1. Die OpenAPI-Datei beschreibt die generelle Form der API — Endpunkte, Standardfelder, Aufrufmuster.
2. Die Blueprints ergänzen zur Laufzeit das, was in Ihrer Installation individuell ist — Ihre Objekte, Ihre Kampagnenstufen, Ihre Zusatzfelder.

Ein KI-Agent kann also erst die allgemeine Beschreibung laden und dann exakt Ihr Feldschema abrufen — und arbeitet damit auf Ihrem konkreten Datenmodell, nicht auf einer Annahme.

Auf Standards gebaut — und deshalb vorhersehbar

Was ein Agent oder ein Automatisierungstool zuverlässig verarbeiten kann, muss berechenbar aufgebaut sein. Die API v2 folgt durchgängig gängigen Konventionen:

• Einheitliche JSON-Struktur für alle Ressourcen, mit Typ, ID, Attributen und Beziehungen im JSON:API-Stil.
• Blättern, Filtern, Sortieren über einheitliche Parameter, dazu das gezielte Einbetten verknüpfter Datensätze und die Beschränkung auf einzelne Felder.
• Standardisierte Fehlermeldungen nach RFC 7807, jede Antwort mit einer eigenen Anfrage-Kennung zur Nachverfolgung.

Diese Vorhersehbarkeit ist kein Selbstzweck: Je einheitlicher die Antworten, desto weniger Sonderfälle muss ein KI-Agent oder ein No-Code-Workflow abfangen.

Einbinden in n8n und andere Tools

Weil die API auf offenen Standards aufsetzt, lässt sie sich in No-Code-Automatisierer wie n8n, Make oder Zapier einbinden — über deren generische HTTP-Bausteine. Die OpenAPI-Datei liefert dafür die Vorlage: Endpunkte, Parameter und Felder sind darin beschrieben, sodass sich Aufrufe schnell zusammenstecken lassen, statt jeden von Hand zu recherchieren.

So automatisieren Sie etwa das Anlegen eines Kunden aus einem Webformular, das Erzeugen einer Rechnung aus einem Fremdsystem oder den nächtlichen Abgleich von Datensätzen. Der Zugang läuft über einen API-Token, den Sie im System vergeben und der sich auf bestimmte Bereiche einschränken lässt; die Verbindung ist per HTTPS abgesichert und für den Zugriff aus dem Browser vorbereitet.

Ein Hinweis zur Ehrlichkeit: Die API arbeitet auf Abruf. Ein Workflow stößt die Abfrage also selbst an — zeitgesteuert oder als Schritt in einer größeren Automatisierung. Für die allermeisten Integrationen ist genau das der übliche und robuste Weg.

Kurz gesagt

Der Aufwand einer Integration steckt selten im Verbinden, sondern im Verstehen des fremden Datenmodells. Die API v2 nimmt diesen Aufwand ab, indem sie sich selbst beschreibt: die generelle Form über eine OpenAPI-Dokumentation, das individuelle Datenmodell über Blueprints zur Laufzeit.

Damit ist die Schnittstelle nicht nur für klassische Anbindungen geeignet, sondern gerade auch für KI-Assistenten und Automatisierungsplattformen, die eine Software eigenständig erkunden und bedienen sollen. Wie ameax KI direkt im Arbeitsablauf nutzt, zeigt das KI-Assistenzsystem; welche Daten Ihnen offenstehen, sehen Sie an Modulen wie dem CRM und der Faktura. Für eine konkrete Integrationsidee sprechen Sie uns an — wir zeigen Ihnen die API v2 in einer Bedarfsanalyse.