Erste Schritte mit der API #

Die Your AI Connector REST-API ermöglicht es Ihnen, Ihre eigene Integration auf Basis Ihres Kontos zu erstellen. Sie können Kontakte erstellen und abrufen, Kampagnen, FAQs, Aufgaben und Termine verwalten, Nachrichten senden, Webhooks registrieren, Analysen lesen und Messaging-Kanäle verbinden – alles, was das Dashboard bietet, lässt sich per Code steuern.

Dies ist die zentrale Seite für die API-Dokumentation. Wenn Sie Your AI Connector mit einem Tool verbinden, das bereits über eine integrierte Anbindung verfügt, benötigen Sie die API möglicherweise gar nicht. Die API ist für benutzerdefinierte Integrationen und Automatisierung in großem Maßstab gedacht.

Basis-URL #

Jede Anfrage wird an dieselbe Basis-Webadresse gesendet, und alle Pfade in dieser Dokumentation beziehen sich darauf:

https://api.youraiconnector.com/v1

Der Kampagnen-Endpunkt lautet also https://api.youraiconnector.com/v1/campaigns, der Kontakte-Endpunkt https://api.youraiconnector.com/v1/contacts und so weiter.

Alle Anfragen müssen über eine sichere Verbindung (HTTPS) erfolgen. Unverschlüsselte HTTP-Anfragen werden abgelehnt.

Einen API-Schlüssel erhalten #

Der API-Zugriff ist eine kostenpflichtige Funktion. Wenn Ihr Plan diese nicht enthält, gibt jede Anfrage einen 403 mit folgendem Inhalt zurück:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Sobald der API-Zugriff für Ihren Plan aktiviert ist, generieren Sie einen Schlüssel über das Dashboard. Die vollständige Schritt-für-Schritt-Anleitung finden Sie unter API Access — kurz gesagt: Gehen Sie zu Settings → Integrations → API Key, um Ihren Schlüssel zu generieren oder neu zu erstellen. Der API-Schlüssel ist ein eigener Bereich unter Integrations, getrennt von Webhooks, und erscheint erst, wenn der API-Zugriff für Ihren Plan aktiviert ist. Behandeln Sie den Schlüssel wie ein Passwort: Er gewährt vollen Zugriff auf Ihr Konto.

Authentifizierung #

Sie können Ihren API-Schlüssel auf vier Arten übermitteln. Alle funktionieren bei jedem Endpunkt, der eine Authentifizierung per API-Schlüssel akzeptiert.

Für den produktiven Einsatz sollten Sie eine der Header-Varianten bevorzugen, damit Ihr Schlüssel nicht in Server-Logs oder im Browserverlauf landet. Die Variante mit Abfrageparametern funktioniert immer und ist am einfachsten für einen einmaligen Test.

Siehe Authentifizierung für eine vollständige Aufschlüsselung jeder Methode, inklusive Beispielen und Hinweisen zur Verwendung.

Ihre erste Anfrage #

Hier ist ein vollständiger, funktionierender Aufruf, der die Kampagnen in Ihrem Konto auflistet. Er verwendet Ihren API-Schlüssel und gibt die neuesten Kampagnen zuerst zurück.

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

Eine erfolgreiche Antwort sieht wie folgt aus:

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}

Erfolgs- und Fehlermeldungen #

Jede JSON-Antwort enthält ein success-Flag, sodass Sie darauf verzweigen können, ohne Statuscodes parsen zu müssen.

Eine erfolgreiche Antwort ist success: true plus die Daten für diesen Endpunkt (der Feldname variiert — campaigns, contacts, data usw.):

{
  "success": true,
  "campaigns": []
}

Eine fehlgeschlagene Antwort ist success: false mit einer für Menschen lesbaren error-Nachricht und einem numerischen error_code, der dem HTTP-Status entspricht:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Überprüfen Sie immer success (oder den HTTP-Status), bevor Sie die Daten lesen. Siehe Fehler & Paginierung für die vollständige Statuscode-Tabelle und Informationen zum Blättern durch große Ergebnismengen.

Ratenbegrenzungen #

Authentifizierte Anfragen sind auf 300 Anfragen pro Minute pro API-Schlüssel begrenzt. Es gibt zudem eine allgemeinere Obergrenze von 1.200 Anfragen pro Minute pro Konto, wobei jede für dieses Konto getätigte authentifizierte Anfrage mitgezählt wird.

Wenn Sie eines der beiden Limits überschreiten, erhalten Sie eine 429-Antwort:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Warten Sie kurz und versuchen Sie es erneut. Sie können Ihre aktuelle Nutzung jederzeit mit GET https://api.youraiconnector.com/v1/api-keys/usage überprüfen; dies gibt zurück, wie viele Anfragen Sie im aktuellen Zeitfenster verbraucht haben und wann es zurückgesetzt wird – nützlich für die Implementierung von clientseitigem Throttling. Siehe API-Schlüssel.

Ressourcen-Leitfäden #

Die unten aufgeführten Ressourcengruppen verfügen jeweils über einen eigenen Leitfaden mit den genauen Pfaden, Anforderungsfeldern und Antwortstrukturen.

Agenten, Einstiegspunkte und Broadcasts #

KI-Agenten, Einstiegspunkte und Broadcasts sind alle in der veröffentlichten OpenAPI-Spezifikation enthalten, sodass Sie deren genaue Felder durchsuchen und Live-Anfragen im API-Explorer ausführen können. Jeder Bereich hat seinen eigenen Leitfaden: KI-Agenten, Einstiegspunkte und Broadcasts.

Diese Dokumentation als Markdown lesen #

Jede Seite in dieser Dokumentation hat ein Gegenstück als reines Markdown: Hängen Sie einfach /index.md an die Seitenadresse an. Diese Seite ist also auch unter https://docs.youraiconnector.com/api/getting-started/index.md verfügbar und wird als reiner Text statt als Webseite zurückgegeben – praktisch, wenn Sie eine Seite in einen KI-Assistenten kopieren oder in ein Skript einbinden möchten.

Um die gesamte Sammlung zu durchsuchen, beginnen Sie bei https://docs.youraiconnector.com/sitemap.xml, wo alle von uns veröffentlichten Seiten aufgelistet sind. Beachten Sie, dass die Dokumentation bewusst von Suchmaschinen ferngehalten wird. Der direkte Abruf dieser Adressen ist daher der vorgesehene Weg, um sie per Code zu erreichen.

Es gibt derzeit keinen schlüsselgeschützten Dokumentations-Endpunkt und keinen Massen-Download – die Markdown-Gegenstücke und die Sitemap bilden die gesamte Schnittstelle, und für beides ist kein API-Schlüssel erforderlich.

Nächste Schritte #

• Authentifizierung — Wählen Sie die richtige Authentifizierungsmethode für Ihre Integration.
• Fehler & Paginierung — Behandeln Sie Fehler und blättern Sie durch Ergebnisse.
• API-Zugriff — Generieren Sie Ihren Schlüssel und sehen Sie sich Praxisbeispiele an.