AI-Agent-API

Ein AI-Agent ist das Gehirn hinter Ihrem Bot: seine Anweisungen, Persönlichkeit, Sprache, Wissen und Tools. Sie erstellen einen Agenten einmal und leiten dann den Datenverkehr an ihn weiter. Dieser Leitfaden behandelt alles, was Sie mit einem Agenten über die API tun können — ihn erstellen, konfigurieren, mit Wissen und Tools ausstatten, Entwürfe überprüfen und Konversationen an ihn weiterleiten.

Basis-URL — https://api.youraiconnector.com/v1
Authentifizierung — Ihr API-Schlüssel (siehe Authentifizierung)
Fehler & Paginierung — siehe Fehler & Paginierung

Alle nachstehenden Beispiele zeigen die ?apiKey=-Abfrageform in cURL und den X-API-Key-Header in JavaScript und Python – beides funktioniert an jedem Endpunkt.

Wenn Sie neu im Konzept der Agenten sind, lesen Sie zuerst AI-Agenten.

Wie ein Agent aufgebaut ist

Vier Dinge werden separat verwaltet, und es ist hilfreich zu wissen, was was ist, bevor Sie beginnen:

Komponente	Was es ist	Wo Sie es festlegen
Konfiguration	Anweisungen, Regeln, Ziel, Persönlichkeit, Sprache, KI-Stufe, Buchungs- und Follow-up-Verhalten	`PUT /agents/{agentId}` oder das spezifischere `PUT /agents/{agentId}/bot-config`
Wissen	FAQs und Wissensquellen (Seiten und Dokumente, die die Plattform für Sie gelesen hat)	FAQs-API und `POST /agents/{agentId}/kb-sources`
Tools	Benutzerdefinierte Funktionen und MCP-Server, die der Agent mitten im Gespräch aufrufen kann	`POST /agents/{agentId}/custom-functions` und `POST /agents/{agentId}/mcp-servers`
Routing	Welche Kanäle und Konversationen diesen Agenten tatsächlich erreichen	Einstiegspunkte — `PUT /entry-points/channel-defaults` und `POST /agents/{agentId}/entry-points`

Ein neuer Agent antwortet niemandem, bis Sie ihn weiterleiten. Das Erstellen eines Agenten bringt ihn nicht auf einen Kanal. Das ist der Schritt, den die meisten Integrationen übersehen — siehe Konversationen an einen Agenten weiterleiten am Ende dieser Seite.

Das Agent-Objekt

Ein vollständiges Agent-Dokument ist groß — mehrere hundert Kilobyte, hauptsächlich seine FAQ-Liste, seine Wissensquellen und alle von Ihrer Website gelesenen Seiteninhalte. Aus diesem Grund gibt die Auflistung eine kurze Zusammenfassungszeile pro Agent zurück, wenn Sie danach fragen:

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Feld	Typ	Beschreibung
`id`	string	Die eindeutige Kennung des Agenten.
`name`	string \| null	Name des Agenten, wie im Dashboard angezeigt.
`active`	boolean \| null	Ob der Agent derzeit antworten darf.
`language`	string \| null	Sprache, in der der Agent antwortet.
`goal`	string \| null	Worauf der Agent hinarbeitet, gekürzt auf die ersten 200 Zeichen (ein nachgestelltes Auslassungszeichen bedeutet, dass es gekürzt wurde).
`tags`	array \| null	Die Tagging-Regeln des Agenten.
`anthropic_model`	string \| null	KI-Qualitätsstufe: `standard`, `economy`, `max` oder `mini`.
`ai_speed`	string \| null	Wie viel Überlegung der Agent vor der Antwort anwendet: `fast`, `fast_thinker`, `balanced` oder `thorough`.
`enable_bookings`	boolean \| null	Ob der Agent Termine buchen darf.
`enable_follow_ups`	boolean \| null	Ob der Agent Follow-up-Nachrichten sendet.
`faq_refs_count`	integer	Wie viele FAQs sich in der Wissensdatenbank dieses Agenten befinden.
`kb_source_refs_count`	integer	Wie viele Wissensquellen damit verknüpft sind.
`created_at`	integer \| null	Erstellungszeitpunkt, Epochen-Millisekunden.
`last_modified_at`	integer \| null	Letzte Änderung, Epochen-Millisekunden.

Das vollständige Dokument fügt alles andere hinzu: instructions, rules, personality, availability, follow_up_config, die verknüpften FAQ- und Wissensquellenlisten, die generierten Textblöcke und jeden Ausführungsstatus (tag_generation, optimize_run).

Einige Antworten enthalten auch substrate_campaign_id. Es ist ein interner Datensatz, der bei älteren Konten geführt wird; Sie müssen nie darauf reagieren, und bei neueren Konten ist er null oder nicht vorhanden.

Agenten auflisten

GET /agents — jeder Agent im Konto, die neuesten zuerst.

Dieser Endpunkt ist nicht paginiert. Standardmäßig wird jeder Agent mit seiner vollständigen Konfiguration zurückgegeben, was sehr umfangreich ist: Ein einzelner Agent kann 580 KB erreichen und ein Konto mit 64 Agenten über 3 MB. Übergeben Sie view=summary für eine kurze Zeile pro Agent und lesen Sie dann den gewünschten Agenten mit Agent abrufen aus.

Abfrageparameter

Parameter	Beschreibung
`view`	Auf `summary` setzen für kurze Zeilen. Jeder andere Wert gibt `400` zurück. Weglassen für vollständige Dokumente.
`fields`	Gilt nur in Verbindung mit `view=summary`. Durch Kommas getrennte Zusammenfassungsschlüssel, die beibehalten werden sollen, zum Beispiel `id,name,active`. `id` ist immer enthalten; unbekannte Namen werden ignoriert.

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]

Antwort (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

Agent erstellen

POST /agents — nur name wird tatsächlich benötigt; senden Sie jede Konfiguration, die Sie bereits kennen, zusammen damit. Ein neuer Agent ist standardmäßig aktiv.

Anfragefelder (alle optional außer name)

Feld	Typ	Beschreibung
`name`	string	Name des Agenten.
`active`	boolean	Ob er sofort antworten darf. Standard ist `true`.
`language`	string	Sprache, in der der Agent antwortet.
`instructions`	string	Primäre Anweisungen, die steuern, wie er mit Kontakten spricht.
`rules`	string	Strenge Regeln, die er immer befolgen muss.
`goal`	string	Das Ergebnis, auf das er hinarbeiten soll.
`personality`	string	Tonfall und Persönlichkeit.
`availability`	object	Aktive Stunden pro Wochentag — siehe Aktive Stunden festlegen.
`ai_speed`	string	`fast`, `fast_thinker`, `balanced` oder `thorough`.
`anthropic_model`	string	`standard`, `economy`, `max` oder `mini`.
`scrape_urls`	string[]	Seiten, die gelesen werden sollen, um die Anweisungen des Agenten zu erstellen.

Einen Agenten von Ihrer Website erstellen. Fügen Sie scrape_urls hinzu, und die Plattform liest diese Seiten und schreibt die Anweisungen für Sie. Die Antwort teilt Ihnen mit, ob diese Generierung gestartet wurde, damit Sie wissen, ob Sie den Agenten auf Fortschritte abfragen müssen.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

Antwort (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued ist true, wenn die Plattform begonnen hat, die Anweisungen von den von Ihnen bereitgestellten Seiten zu schreiben.

Ein 400 bedeutet, dass der Body kein JSON-Objekt war, ein Feld abgelehnt wurde oder der Agent die Konfigurationsgröße überschreitet, die Ihr Plan zulässt. Ein 403 bedeutet, dass das Konto eine der gesendeten Einstellungen nicht verwenden darf — zum Beispiel eine KI-Stufe, die der Kontobetreiber nicht gewährt hat.

Agent abrufen

GET /agents/{agentId}

Übergeben Sie fields mit einer durch Kommas getrennten Liste, um nur das zurückzuerhalten, was Sie benötigen, zum Beispiel fields=name,active,goal. Die id ist immer enthalten, und Namen, die auf dem Agenten nicht existieren, werden ignoriert, anstatt abgelehnt zu werden. Lassen Sie es weg, um das gesamte Dokument zu erhalten.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

Ein Agent, der in Ihrem Konto nicht existiert, gibt 404 zurück.

Agent aktualisieren

PUT /agents/{agentId} — senden Sie nur die Felder, die Sie ändern möchten; alles andere bleibt unverändert.

Verschachtelte Einstellungen können Blatt für Blatt mit einem punktierten Schlüssel adressiert werden, sodass "availability.monday" nur den Montag ändert und den Rest der Woche unverändert lässt.

Hinweise

Um zu ändern, für welchen buchbaren Ereignistyp der Agent Buchungen vornimmt, senden Sie event_id (die ID des Ereignisses oder null, um sie zu löschen). Senden Sie event_ids mit einem Array, um mehrere gleichzeitig zu verknüpfen – das erste wird zum primären, und [] hebt alle Verknüpfungen auf. event_id und event_ids schließen sich gegenseitig aus, und das Feld event selbst kann nicht direkt beschrieben werden.
enable_bookings muss ein echter boolescher Wert sein, und booking_provider muss einer der Werte default, zenchef, formitable sein.
Felder für Eigentümerschaft und Identität werden ignoriert, ebenso wie der interne Ausführungsstatus (Generierungs- und Optimierungsfortschritt).
Das Routing wird hier nicht festgelegt. Verwenden Sie PUT /entry-points/channel-defaults, um den Agenten als Antwortenden für einen Kanal festzulegen, POST /agents/{agentId}/entry-points für Schlüsselwort- und Kommentarregeln und PATCH /agents/{agentId}/active, um ihn anzuhalten oder fortzusetzen.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

Antwort (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Ein leerer Body gibt 400 mit "No fields to update" zurück.

Bot-Einstellungen aktualisieren

PUT /agents/{agentId}/bot-config – der gezielte Weg, um nur die Konversationseinstellungen zu ändern.

Ein Agent hat keinen separaten Bot-Bereich: Seine Einstellungen befinden sich direkt auf dem Agenten, daher sind die Feldnamen hier dieselben, die Sie an PUT /agents/{agentId} senden würden. Dieser Endpunkt existiert als sichere, fokussierte Methode, um eine Handvoll davon zu ändern. Mindestens ein Feld ist erforderlich.

Feld	Beschreibung
`instructions`	Primäre Anweisungen, die steuern, wie der Agent mit Kontakten spricht.
`rules`	Strenge Regeln, die er immer befolgen muss.
`goal`	Das Ergebnis, auf das er in jeder Konversation hinarbeiten soll.
`personality`	Beschreibung von Tonalität und Persönlichkeit.
`language`	Sprache, in der der Agent antwortet.
`ai_speed`	`fast`, `fast_thinker`, `balanced` oder `thorough`.
`anthropic_model`	`standard`, `economy`, `max` oder `mini`.
`max_messages`	Maximale Anzahl an Agenten-Nachrichten pro Konversation.
`alert_human_when`	Wann der Agent einen menschlichen Teamkollegen benachrichtigen soll.
`ai_transparency`	Ob der Agent offenlegt, dass er eine KI ist.

Feldnamen müssen hier einfache Namen sein – Buchstaben, Zahlen, Unterstriche und Bindestriche. Punktierte Pfade werden an diesem Endpunkt nicht akzeptiert (im Gegensatz zu PUT /agents/{agentId}), daher wird bot.goal mit einem 400 abgelehnt.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

Langer Text wird auf die Konfigurationsgröße angerechnet, die Ihr Plan zulässt, daher kann ein sehr großer Anweisungssatz mit einem 400 abgelehnt werden.

Aktive Stunden festlegen

PUT /agents/{agentId}/active-hours – die Stunden, in denen der Agent automatisch antwortet. Außerhalb dieser Zeitfenster bleibt er inaktiv.

Senden Sie ein availability-Objekt, das nach Wochentagen (monday bis sunday) gegliedert ist. Jeder Tag akzeptiert ein einzelnes Zeitfenster oder eine Liste von Fenstern im 24-Stunden-Format HH:MM. Tage, die Sie auslassen, behalten ihre bisherigen Einstellungen, und jeder Schlüssel, der kein Wochentag ist, wird abgelehnt – so kann ein Tippfehler nicht unbemerkt bleiben.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

Antwort (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Ein ungültiger Wochentags-Schlüssel gibt 400 zurück: "Invalid availability keys: funday. Allowed keys: monday through sunday."

Einen Agenten anhalten oder fortsetzen

PATCH /agents/{agentId}/active — schaltet den Agenten ein oder aus. Ein pausierter Agent behält seine gesamte Konfiguration bei, antwortet aber sofort nicht mehr; das Fortsetzen wird unmittelbar wirksam.

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

Antwort (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active muss ein echter boolescher Wert sein – alles andere gibt 400 mit "active (boolean) is required" zurück.

Einen Agenten duplizieren

POST /agents/{agentId}/duplicate — erstellt eine Kopie unter Beibehaltung der Konfiguration. Die Kopie sendet nichts, bis Sie einen Kanal oder einen Einstiegspunkt darauf verweisen.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"

Antwort (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

Ein Duplikat zählt bei Ihrem Tarif genauso auf das Agenten-Kontingent wie die Neuerstellung, daher wird es mit 403 abgelehnt, wenn das Konto sein Limit erreicht hat.

Einen Agenten löschen

DELETE /agents/{agentId}

Das Löschen wird verweigert, solange der Agent noch mit etwas verknüpft ist, das ohne ihn nicht mehr funktionieren würde – eine Übertragung, ein Einstiegspunkt oder (bei älteren Konten) eine Kampagne. Die Antwort listet auf, was den Agenten blockiert, damit Sie diese Verknüpfungen zuerst lösen und es erneut versuchen können.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"

Antwort (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Blockiert (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

Entwürfe: Änderungen überprüfen, bevor sie live gehen

Änderungen, die im Editor vorgenommen wurden, sowie alle durch Mit KI optimieren erstellten Neufassungen werden als unveröffentlichter Entwurf gespeichert, bis Sie sie veröffentlichen. Der Live-Agent antwortet bis dahin weiterhin mit seiner aktuellen Konfiguration.

Den Entwurf veröffentlichen

POST /agents/{agentId}/publish-draft — überträgt den Entwurf auf die Live-Konfiguration und löscht den Entwurf im selben Schritt.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

Antwort (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

published_keys listet die Einstellungen auf, die vom Entwurf auf den Live-Agenten übertragen wurden, damit Sie sehen können, was sich geändert hat.

Prüfen Sie vor dem Aufruf, ob ein Entwurf existiert. Das Veröffentlichen eines Agenten ohne Entwurf ist kein unterstützter Aufruf und führt derzeit zu einem 500 mit einer allgemeinen Meldung, nicht mit einer spezifischen. Um einen Entwurf stattdessen zu verwerfen, verwenden Sie unten „Verwerfen“.

Entwurf verwerfen

POST /agents/{agentId}/discard-draft – verwirft den Entwurf und belässt die Live-Konfiguration unverändert. Kann sicher aufgerufen werden, wenn kein Entwurf vorhanden ist; es passiert nichts.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

Einen Agenten mit KI optimieren

POST /agents/{agentId}/optimize – schreibt die Konfiguration des Agenten basierend auf Ihrem Feedback um („er bietet ständig Rabatte an“, „die Antworten sind zu lang“) und speichert die Überarbeitung als Entwurf, anstatt sie live zu schalten.

Senden Sie entweder user_feedback (eine einfache Anweisung) oder, wenn Sie auf eine bestimmte schlechte Antwort reagieren, thumbs_down_feedback zusammen mit der fehlerhaften thumbs_down_message. Mindestens eines der beiden muss Text enthalten.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

Antwort (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Die Arbeit läuft im Hintergrund und der Aufruf kehrt sofort zurück. Lesen Sie den Agenten mit GET /agents/{agentId} und beobachten Sie optimize_run.status; sobald der Status wieder Draft ist, wartet die Überarbeitung als Entwurf des Agenten. Überprüfen Sie diese und veröffentlichen oder verwerfen Sie sie anschließend.

Nur ein Durchlauf gleichzeitig pro Agent – ein zweiter Aufruf, während einer aktiv ist, gibt 409 zurück. Dies verbraucht KI-Credits.

Tagging-Regeln

Eine Tagging-Regel besteht aus einem Tag und einer Beschreibung, wann es angewendet werden soll. Während eines Gesprächs liest der Agent diese Beschreibung und versieht den Kontakt mit dem Tag, wenn es passt. So werden Tag-basierte Automatisierungen ausgelöst.

Das Regel-Objekt

Feld	Erforderlich	Beschreibung
`name`	Ja	Das anzuwendende Tag, zum Beispiel `hot-lead`.
`description`	Nein	Wann der Agent es anwenden soll, geschrieben als Anweisung, der er folgt.
`webhook`	Nein	URL, die aufgerufen wird, wenn der Agent dieses Tag anwendet.
`ai_can_remove`	Nein	Ob der Agent das Tag auch wieder entfernen darf. Standardmäßig `false`.
`tag_id`	Nein	ID eines bestehenden Tags in Ihrem Konto, um die Regel damit zu verknüpfen. Ohne diese Angabe wird die Regel mit dem Tag gleichen Namens verknüpft und erstellt dieses, falls es noch nicht existiert – so kann jede Regel nachträglich über die Tag-ID adressiert werden.

Tagging-Regel hinzufügen

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

Antwort (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

Tagging-Regel ersetzen

PUT /agents/{agentId}/tags/{tagId} – die Regel wird anhand der Tag-ID im Pfad gefunden und vollständig ersetzt, nicht zusammengeführt. Senden Sie daher die vollständige Regel und nicht nur den Teil, den Sie ändern möchten. Das Tag, auf das sie verweist, bleibt erhalten, selbst wenn Sie tag_id weglassen; eine Bearbeitung kann die Regel also nicht von ihrem Tag trennen.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

Eine Tagging-Regel entfernen

DELETE /agents/{agentId}/tags/{tagId} – der Agent wendet dieses Tag nicht mehr an. Das Tag selbst und alle Kontakte, die es bereits tragen, bleiben unverändert.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

Beide Endpunkte geben 404 zurück, wenn der Agent nicht existiert oder wenn er keine Regel für dieses Tag hat.

Ein Tag-Set mit KI generieren

POST /agents/{agentId}/tags/generate – entwirft ein vollständiges Set an Regeln (die Tag-Namen und die Formulierung „Anwenden, wenn…“ hinter jedem), indem die eigenen Anweisungen und Ziele des Agenten gelesen werden.

Feld	Beschreibung
`mode`	`merge` (der Standardwert) behält die bereits auf dem Agenten vorhandenen Regeln bei und ergänzt sie. `replace` entwirft das Set von Grund auf neu.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

Antwort (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

Die Arbeit läuft im Hintergrund. Lesen Sie den Agenten aus und beobachten Sie tag_generation.status; die Regeln selbst landen im tags des Agenten. Es ist immer nur ein Durchlauf pro Agent möglich (409 andernfalls), und es werden KI-Credits verbraucht.

Wissensquellen

Wissensquellen sind die Seiten und Dokumente, die die Plattform für Sie gelesen hat. Wenn Sie eine solche an einen Agenten anhängen, kann dieser auf Basis dieser Inhalte antworten.

Woher Quellen-IDs stammen. Fügen Sie Inhalte mit den Knowledge-Base-Endpunkten hinzu – POST /kb-sources/url für eine Seite, POST /kb-sources/file für ein Dokument, POST /kb-sources/bulk-import für eine ganze Website. Diese geben eine source_id zurück, die Sie mit GET /kb-sources/{sourceId} abfragen, bis sie bereit ist. POST /kb-sources/url akzeptiert auch autoLinkToAgentId, wodurch die Quelle an einen Agenten angehängt wird, sobald der Import abgeschlossen ist, sodass Sie den unten stehenden „Attach“-Aufruf überspringen können.

Wissensquellen anhängen

POST /agents/{agentId}/kb-sources – senden Sie kb_source_ids mit einer Liste, um ein ganzes Set in einem Aufruf anzuhängen (was Sie nach dem Crawlen einer Website wünschen), oder kb_source_id für eine einzelne Quelle. Senden Sie entweder das eine oder das andere. Das Anhängen von etwas, das bereits angehängt ist, ändert nichts.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

Antwort (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

Wissensquellen trennen

DELETE /agents/{agentId}/kb-sources/{kbSourceId} für einen oder POST /agents/{agentId}/kb-sources/bulk-remove mit kb_source_ids für mehrere. Das Massenlöschen ist ein POST, da die Liste der IDs im Body übertragen wird.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

Die Quellen selbst werden nicht gelöscht und bleiben für Ihre anderen Agents verfügbar. Das Trennen einer nicht verknüpften Quelle bewirkt nichts.

FAQs

FAQs werden über eigene Endpunkte verwaltet und von dort aus mit einem Agent verknüpft: POST /faqs/{faqId}/link mit { "agent_id": "ag7HkQ2ZpLxR3mNb" }, und POST /faqs/{faqId}/unlink, um die Verknüpfung wieder aufzuheben. Ein FAQ kann von beliebig vielen Agents gemeinsam genutzt werden. Siehe die FAQs API.

Ein FAQ wird nur von den Agents verwendet, mit denen es verknüpft ist – das Erstellen allein reicht nicht aus.

Tools

Benutzerdefinierte Funktionen

POST /agents/{agentId}/custom-functions ermöglicht es dem Agent, während Unterhaltungen eine Ihrer benutzerdefinierten Funktionen aufzurufen. Es können nur Funktionen verknüpft werden, die zum selben Konto gehören; das Verknüpfen einer bereits verknüpften Funktion bewirkt nichts.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} trennt die Verbindung. Die Funktion selbst wird nicht gelöscht und bleibt für Ihre anderen Agents verfügbar.

Verwalten Sie die Funktionen selbst unter /custom-functions – siehe Benutzerdefinierte Funktionen, um zu erfahren, worum es sich dabei handelt.

MCP-Server

Ein MCP-Server ist ein fertiges Paket von Tools, die Ihr Agent selbst entdecken und aufrufen kann – siehe Verbinden von MCP-Servern mit Ihrem Bot. Server werden einmalig für das Konto registriert und dann den Agents zugewiesen, die sie verwenden sollen.

MCP-Server erfordern die Funktion Benutzerdefinierte Funktionen in Ihrem Plan. Ohne diese geben die /mcp-servers-Endpunkte auf Kontoebene 403 zurück. Das Zuweisen eines bereits registrierten Servers zu einem Agent ist nicht eingeschränkt.

Einen Server registrieren

POST /mcp-servers

Feld	Erforderlich	Beschreibung
`name`	Ja	Eine Bezeichnung für den Server.
`url`	Ja	Die Adresse des Servers. Muss über das öffentliche Internet erreichbar sein.
`auth_type`	Nein	`header` (Standard) für einen statischen Authentifizierungs-Header oder `oauth2`.
`auth_header_name`	Nein	Header, in dem die Anmeldeinformationen gesendet werden. Standard ist `Authorization`.
`auth_header_value`	Nein	Die Anmeldeinformation selbst. Wird niemals in einer Antwort zurückgegeben.
`enabled`	Nein	Ob der Server für Agents verfügbar ist. Standard ist `true`.
`enabled_tools`	Nein	Positivliste der Tool-Namen. `null` bedeutet, dass jedes vom Server angebotene Tool aktiviert ist.
`tool_policies`	Nein	Limits pro Tool, sortiert nach Tool-Name – wie oft ein Tool ausgeführt werden darf, Ergebnis-Caching und ein Schreibschutz-Override. Übergeben Sie `null`, um alle zu löschen.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

Antwort (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

Beim Speichern verbindet sich die Plattform mit dem Server und speichert die Liste der angebotenen Tools zwischen. Ein Server, der nicht erreicht werden kann, wird dennoch gespeichert, mit dem Grund in last_error und einer leeren Tool-Liste – so können Sie sich zuerst registrieren und die Konnektivität später beheben.

Ein auth_type von oauth2 speichert die Registrierung mit oauth_connected: false und ohne Tools: Es gibt noch kein Token. Die Autorisierung eines OAuth-Servers erfordert eine Anmeldung über den Browser und erfolgt über das Dashboard, nicht über die API.

Server auflisten, aktualisieren und löschen

GET /mcp-servers — jeder registrierte Server, neueste zuerst, unter servers.
PUT /mcp-servers/{serverId} — senden Sie nur das, was Sie ändern möchten. Das Ändern der URL oder der Auth-Felder testet die Verbindung erneut und aktualisiert die zwischengespeicherte Tool-Liste.
DELETE /mcp-servers/{serverId} — entfernt die Registrierung und hebt die Verknüpfung mit jedem Agenten und jeder Kampagne auf, für die er aktiviert war.

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

Geheimnisse werden nie zurückgegeben. Antworten enthalten auth_header_value_set (ein true/false-Flag, das angibt, dass ein Wert gespeichert ist) anstelle der Anmeldedaten, und OAuth-Token sowie Client-Geheimnisse bleiben serverseitig. Alles andere wird zurückgegeben: name, url, enabled, auth_type, auth_header_name, tools, enabled_tools, tool_policies, oauth_connected, tools_cached_at, last_connected_at, last_error, created_at, updated_at.

Verbindung testen

POST /mcp-servers/test-connection — verbindet sich mit einem Server und listet dessen Tools auf. Zwei Möglichkeiten, dies aufzurufen:

mit server_id — testet die gespeicherte Konfiguration und aktualisiert die zwischengespeicherte Tool-Liste;
mit einem Inline-url (plus auth_header_name / auth_header_value) — ein Test vor dem Speichern, der nichts speichert.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

Antwort (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

Ein Verbindungsfehler ist kein HTTP-Fehler – Sie erhalten ein 200 mit success: false und eine error, die beschreibt, was schiefgelaufen ist, sodass Sie dies neben dem Feld anzeigen können, das der Benutzer gerade bearbeitet.

Server an einen Agenten anhängen

Die Registrierung eines Servers gibt keinem Agenten Zugriff darauf. Hängen Sie ihn an:

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

Antwort (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} trennt die Verbindung wieder. Der Server selbst wird nicht gelöscht und bleibt für Ihre anderen Agenten verfügbar. Das Anhängen oder Trennen von etwas, das sich bereits in diesem Zustand befindet, ändert nichts.

Medienbibliothek

Die Medienbibliothek enthält die Dateien, die ein Agent während eines Gesprächs senden darf – ein Menü, eine Preisliste, ein Produktfoto. Ein Agent kann maximal 50 Elemente enthalten.

Medien auflisten

GET /agents/{agentId}/media-library

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"

Antwort (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

Elemente, die auf dem Agenten gespeichert sind, kommen zuerst, gefolgt von älteren Elementen, die noch auf der Kampagne gespeichert sind, aus der der Agent erstellt wurde; media_home (agent oder campaign) gibt an, was was ist. Innerhalb jeder Gruppe erscheint das Neueste zuerst.

media_url läuft nach 7 Tagen ab. Es handelt sich um den Download-Link, der beim Hochladen der Datei erstellt wurde – betrachten Sie einen alten Link eher als veraltet denn als defekt und lesen Sie die Liste erneut, um einen neuen Link zu erhalten.

Medien hochladen

POST /agents/{agentId}/media-library – die Datei wird inline als base64 hochgeladen, bis zu 10 MB. Der Aufruf kehrt zurück, sobald die Datei gespeichert ist, planen Sie also etwas mehr Zeit ein als für eine normale Anfrage. Beachten Sie, dass dieser Body camelCase-Feldnamen verwendet.

Feld	Erforderlich	Beschreibung
`base64Data`	Ja	Dateiinhalt, base64-kodiert, ohne data-URL-Präfix.
`mimeType`	Ja	MIME-Typ der Datei.
`fileName`	Ja	Ursprünglicher Dateiname, der zur Benennung der gespeicherten Datei verwendet wird.
`title`	Nein	Kurze Bezeichnung, die in der Bibliothek angezeigt wird.
`description`	Nein	Die Anweisung „Wann soll der Agent dies senden“.
`sendMessage`	Nein	Bevorzugter Wortlaut, den der Agent verwendet, wenn er das Element sendet. Auf 500 Zeichen gekürzt.
`maxSendsPerConversation`	Nein	Wie oft es an denselben Kontakt in einer Konversation gesendet werden darf. Standardwert ist `1`.
`sendAsVoiceNote`	Nein	Nur Audio-Uploads – speichert die Datei als WhatsApp-Sprachnachricht. Wird bei anderen Dateitypen ignoriert.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

Zwei Dinge geschehen automatisch: Ein animiertes GIF wird in ein Video konvertiert, damit es auf jedem Kanal abgespielt werden kann, und die Plattform schreibt eine kurze Zusammenfassung dessen, was sich tatsächlich in der Datei befindet, damit der Agent weiß, wann sie passt.

Ein 400 deckt fehlende Felder, einen nicht unterstützten Dateityp, eine leere oder zu große Datei sowie das Erreichen des Limits von 50 Elementen ab. Ein 403 bedeutet, dass die Medienbibliothek für das Konto deaktiviert ist.

Ein Medienelement aktualisieren

PATCH /agents/{agentId}/media-library/{itemId} – nur Metadaten. Die Datei selbst kann nicht ersetzt werden; laden Sie ein neues Element hoch und löschen Sie das alte. Dieser Body verwendet snake_case: title, description, send_message, max_sends_per_conversation (eine nicht-negative ganze Zahl oder null, um das Limit aufzuheben).

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

Antwort (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

Ein Medienelement löschen

DELETE /agents/{agentId}/media-library/{itemId} – entfernt das Element und die zugehörige gespeicherte Datei. Das Löschen eines bereits entfernten Elements ist erfolgreich und meldet deleted: false, sodass der Aufruf sicher wiederholt werden kann.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

Follow-up-Nachrichten generieren

POST /agents/{agentId}/template-generation – schreibt die Follow-up-Nachrichten des Agenten für Sie (die Stupser, die er sendet, wenn eine Konversation ruhig wird), basierend auf dem Zweck des Agenten.

Feld	Beschreibung
`type`	`all` (Standard) schreibt den gesamten Satz. `cold_only` schreibt nur die Nachrichten für Kontakte, die nie geantwortet haben.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

Es gibt zwei Möglichkeiten, wie dies zurückgegeben wird, und das Feld target gibt an, welche:

target: "agent" mit einem 200 — die Nachrichten wurden während des Anrufs geschrieben und das Ergebnis befindet sich in data. Lesen Sie diese aus dem follow_up_config des Agenten aus. Dies ist der Normalfall.
target: "campaign" mit einem 202 — die Arbeit wurde für die in campaign_id benannte Kampagne in die Warteschlange gestellt. Überwachen Sie den template_generation_status dieser Kampagne, bis sie abgeschlossen ist.

cold_only benötigt eine ausgehende Kampagne und wird mit 409 (reason: "cold_only_requires_campaign") abgelehnt, wenn der Agent keine hat. Ein 403 bedeutet, dass automatische Nachfassaktionen für das Konto nicht aktiviert sind. Dies verbraucht KI-Credits, und ein 400 mit "Insufficient credits." bedeutet, dass das Konto keine mehr hat.

Konversationen an einen Agenten weiterleiten

Ein Agent beantwortet nur die Konversationen, die ihm von einem Einstiegspunkt gesendet werden. Bis ein Kanal einen solchen hat, wird die erste Nachricht von jemandem, mit dem Sie noch nie gesprochen haben, zwar gespeichert, aber niemand nimmt sie entgegen und kein Assistent antwortet.

Was Sie tun möchten	Aufruf
Einen Agenten zum Antwortenden für einen ganzen Kanal machen	`PUT /entry-points/channel-defaults` mit `{ "channel": "instagram", "agent_id": "AGENT_ID" }`
Eine engere Regel hinzufügen (Schlüsselwörter, Kommentare, neue Follower)	`POST /agents/{agentId}/entry-points`
Die Regeln anzeigen, die auf einen Agenten verweisen	`GET /agents/{agentId}/entry-points`
Einen Kanal ohne Antwortenden hinterlassen	`DELETE /entry-points/channel-defaults?channel=instagram`

Einstiegspunkte eines Agenten auflisten

GET /agents/{agentId}/entry-points — die Routing-Regeln, die Konversationen an diesen Agenten senden, beginnend mit der neuesten. Sowohl aktuelle als auch zurückgezogene Regeln werden zurückgegeben; eine zurückgezogene Regel hat enabled: false.

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

Für die Kanal-Standardeinstellungen des gesamten Kontos, einschließlich eines Kanals, der absichtlich auf „niemand“ gesetzt wurde, lesen Sie stattdessen GET /entry-points/channel-defaults.

Einen Einstiegspunkt erstellen

POST /agents/{agentId}/entry-points — der Agent im Pfad gewinnt immer, daher kann niemals eine Regel für einen anderen Agenten erstellt werden als den, der in der URL angegeben ist.

`type`	Was es bewirkt
`channel_default`	Der Agent antwortet jedem neuen Kontakt auf den aufgeführten Kanälen. Bevorzugen Sie hierfür `PUT /entry-points/channel-defaults` – dies zieht den vorherigen Antwortenden für Sie zurück, was das Erstellen eines zweiten Standards an dieser Stelle nicht tut.
`keyword`	Der Agent übernimmt, wenn die erste Nachricht eines der `match_config.keywords` enthält. Mindestens ein Schlüsselwort ist erforderlich.
`instagram_comment` / `facebook_comment`	Der Agent antwortet auf Kommentare zu Ihren Beiträgen. Der passende Kanal muss in `channels` aufgeführt sein.
`instagram_follower`	Der Agent begrüßt neue Follower.

channels ist erforderlich und gibt an, welche Kanäle die Regel abdeckt – zum Beispiel whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget oder custom_channel. Neue Regeln sind aktiviert, sofern Sie nichts anderes angeben.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

Antwort (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Welche Regel gewinnt, wenn mehrere zutreffen könnten: Eine laufende Konversation oder eine manuelle Zuweisung behält den Agenten, den sie bereits hat; ansonsten haben Schlüsselwortregeln Vorrang vor Kommentarregeln, diese vor Follower-Regeln, und ein Kanal-Standard ist das letzte Mittel. Ob diese Regeln auf einem Konto bereits etwas entscheiden, wird durch GET /entry-points/routing-status gemeldet.

Dies ist die Kurzfassung. Der Leitfaden zur Entry Points API behandelt die vollständige Hierarchie, Regeln für Kommentare und Follower, einen Agenten pro WhatsApp-Nummer sowie das Ändern oder Löschen einer Regel. Siehe Entry Points für das Konzept und die Channels API für die Verbindung des Kanals selbst.

Fehler der AI Agents API

Agent-Endpunkte geben das Standard-Fehler-Envelope zurück:

{
  "success": false,
  "error": "Agent not found"
}

Status	Wann dies bei einem Agent-Endpunkt auftritt
`400`	Ein erforderliches Feld fehlt oder ist ungültig – ein leerer Update-Body, ein Wert außerhalb einer zulässigen Liste (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), ein Schlüssel, der kein Wochentag ist, in `availability`, ein punktierter Feldname in `bot-config` oder eine falsch formatierte ID im Pfad.
`403`	Das Konto darf eine von Ihnen gesendete Einstellung nicht verwenden, Sie haben das Agent-Limit Ihres Tarifs erreicht oder eine Funktion, die dieser Endpunkt benötigt (Mediathek, Follow-ups, benutzerdefinierte Funktionen für MCP-Server), ist deaktiviert. Eine Änderung, die die in Ihrem Tarif zulässige Konfigurationsgröße überschreitet, wird mit `400` abgelehnt.
`404`	Der Agent, die Tag-Regel, das Medienelement oder der MCP-Server wurde nicht gefunden – entweder existiert er nicht oder er gehört zu einem anderen Konto.
`409`	Etwas ist bereits in Bearbeitung oder im Weg: Eine Optimierung oder Tag-Generierung läuft, der Agent ist noch mit einem Broadcast, einem Einstiegspunkt oder einer Kampagne verknüpft, oder `cold_only` wurde ohne ausgehende Kampagne angefordert.

Die gemeinsamen Codes, die jeder Endpunkt zurückgeben kann — 401, 403 (Ihr Plan beinhaltet keinen API-Zugriff), 429 (Ratenbegrenzung) und 500 — sind zusammen mit Hinweisen zur Wiederholung unter Fehler & Paginierung aufgeführt.

Ein Hinweis zum Explorer. Die /agents-Endpunkte sind in der veröffentlichten OpenAPI-Spezifikation enthalten, sodass Sie deren genaue Felder durchsuchen und Live-Anfragen in der API-Referenz ausführen können. Die /mcp-servers-Endpunkte auf Kontoebene sind ebenfalls in der Spezifikation enthalten, sodass Sie diese dort ebenfalls erkunden können.

AI-Agent-API #

Wie ein Agent aufgebaut ist #

Das Agent-Objekt #

Agenten auflisten #

Agent erstellen #

Agent abrufen #

Agent aktualisieren #

Bot-Einstellungen aktualisieren #

Aktive Stunden festlegen #

Einen Agenten anhalten oder fortsetzen #

Einen Agenten duplizieren #

Einen Agenten löschen #

Entwürfe: Änderungen überprüfen, bevor sie live gehen #

Den Entwurf veröffentlichen #

Entwurf verwerfen #

Einen Agenten mit KI optimieren #

Tagging-Regeln #

Tagging-Regel hinzufügen #

Tagging-Regel ersetzen #

Eine Tagging-Regel entfernen #

Ein Tag-Set mit KI generieren #

Wissensquellen #

Wissensquellen anhängen #

Wissensquellen trennen #

FAQs #

Tools #

Benutzerdefinierte Funktionen #

MCP-Server #

Einen Server registrieren #

Server auflisten, aktualisieren und löschen #

Verbindung testen #

Server an einen Agenten anhängen #

Medienbibliothek #

Medien auflisten #

Medien hochladen #

Ein Medienelement aktualisieren #

Ein Medienelement löschen #

Follow-up-Nachrichten generieren #

Konversationen an einen Agenten weiterleiten #

Einstiegspunkte eines Agenten auflisten #

Einen Einstiegspunkt erstellen #

Fehler der AI Agents API #

Verwandte Themen #

AI-Agent-API

Wie ein Agent aufgebaut ist

Das Agent-Objekt

Agenten auflisten

Agent erstellen

Agent abrufen

Agent aktualisieren

Bot-Einstellungen aktualisieren

Aktive Stunden festlegen

Einen Agenten anhalten oder fortsetzen

Einen Agenten duplizieren

Einen Agenten löschen

Entwürfe: Änderungen überprüfen, bevor sie live gehen

Den Entwurf veröffentlichen

Entwurf verwerfen

Einen Agenten mit KI optimieren

Tagging-Regeln

Tagging-Regel hinzufügen

Tagging-Regel ersetzen

Eine Tagging-Regel entfernen

Ein Tag-Set mit KI generieren

Wissensquellen

Wissensquellen anhängen

Wissensquellen trennen

FAQs

Tools

Benutzerdefinierte Funktionen

MCP-Server

Einen Server registrieren

Server auflisten, aktualisieren und löschen

Verbindung testen

Server an einen Agenten anhängen

Medienbibliothek

Medien auflisten

Medien hochladen

Ein Medienelement aktualisieren

Ein Medienelement löschen

Follow-up-Nachrichten generieren

Konversationen an einen Agenten weiterleiten

Einstiegspunkte eines Agenten auflisten

Einen Einstiegspunkt erstellen

Fehler der AI Agents API

Verwandte Themen