# 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. ::: note **Hinweis:** Diese Seiten sind für Entwickler geschrieben. Wenn Sie kein Entwickler sind, teilen Sie diesen Abschnitt mit Ihrem technischen Team. ::: --- ## 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: ```json { "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](../integrations/api-access.md) — 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. | Methode | Wie | Am besten geeignet für | |---|---|---| | Abfrageparameter | `?apiKey=YOUR_API_KEY` | Schnelle Tests, Browser-URLs, ältere Setups | | Header | `X-API-Key: YOUR_API_KEY` | Produktiv-Integrationen | | Bearer-Header | `Authorization: Bearer YOUR_API_KEY` | Produktiv-Integrationen | | Firebase-ID-Token | `Authorization: Bearer ` | Nur für First-Party-App-Sitzungen | 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](authentication.md) 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** ```bash curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10" ``` **JavaScript** ```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** ```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: ```json { "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.): ```json { "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: ```json { "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](errors-and-pagination.md) 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: ```json { "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](api-keys.md). --- ## Ressourcen-Leitfäden Die unten aufgeführten Ressourcengruppen verfügen jeweils über einen eigenen Leitfaden mit den genauen Pfaden, Anforderungsfeldern und Antwortstrukturen. | Ressource | Was sie abdeckt | |---|---| | [AI Agents](agents.md) | Erstellen und konfigurieren Sie KI-Agenten: Einstellungen, aktive Zeiten, Wissen, Tagging-Regeln, Tools, Medien und Entwürfe | | [Entry Points](entry-points.md) | Legen Sie fest, welcher KI-Agent eine neue Konversation beantwortet: Kanal-Standards, ein Agent pro WhatsApp-Nummer, Stichwort-, Kommentar- und Follower-Regeln | | [Broadcasts](broadcasts.md) | Erstellen, bepreisen, starten, pausieren und duplizieren Sie einmalige Sendungen an eine Kontaktliste | | [Campaigns](campaigns.md) | Erstellen, aktualisieren, duplizieren, aktivieren, archivieren und überprüfen Sie Kampagnen sowie deren Bot-Konfiguration | | [Contacts](contacts.md) | Erstellen, suchen, auflisten, aktualisieren, importieren, taggen und löschen Sie Kontakte | | [FAQs](faqs.md) | Verwalten Sie die Frage-Antwort-Einträge, die Ihr KI-Assistent verwendet, und verknüpfen Sie diese mit Kampagnen | | [Knowledge Base](knowledge-base.md) | Importieren Sie Websites und Dokumente in das Wissen Ihrer KI und bündeln Sie FAQs in Gruppen | | [Tasks](tasks.md) | Erstellen und verwalten Sie CRM-Aufgaben, Board-Phasen und Aufgabentypen | | [Messages](messages.md) | Senden Sie ausgehende Nachrichten und lesen Sie den Konversationsverlauf | | [Appointments](appointments.md) | Buchen, verschieben, stornieren und löschen Sie Termine | | [Channels](channels.md) | Verbinden und trennen Sie Messaging-Kanäle, kaufen Sie Nummern und legen Sie fest, welcher KI-Agent neue Konversationen auf dem jeweiligen Kanal beantwortet | | [Templates](templates.md) | Erstellen, übermitteln und überprüfen Sie den Genehmigungsstatus von WhatsApp-Nachrichtenvorlagen | | [Analytics](analytics.md) | Lesen Sie tägliche Nachrichtenereignis-Statistiken, die Kreditnutzung und KI-Kostenaufstellungen | | [Webhooks](webhooks.md) | Registrieren Sie Endpunkte, um Echtzeit-Ereignisbenachrichtigungen zu erhalten | | [Team](team.md) | Verwalten Sie Teammitglieder, Einladungen, Rollen, Berechtigungen und Abteilungen | | [API Keys](api-keys.md) | Überprüfen, rotieren und widerrufen Sie Ihren API-Schlüssel, prüfen Sie die Ratenbegrenzungsnutzung und erstellen Sie zusätzliche Schlüssel mit eingeschränktem Zugriff | ### 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](reference.md) ausführen können. Jeder Bereich hat seinen eigenen Leitfaden: [KI-Agenten](agents.md), [Einstiegspunkte](entry-points.md) und [Broadcasts](broadcasts.md). --- ## 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](authentication.md) — Wählen Sie die richtige Authentifizierungsmethode für Ihre Integration. - [Fehler & Paginierung](errors-and-pagination.md) — Behandeln Sie Fehler und blättern Sie durch Ergebnisse. - [API-Zugriff](../integrations/api-access.md) — Generieren Sie Ihren Schlüssel und sehen Sie sich Praxisbeispiele an.