API-Referenz
Alle öffentlichen Ressourcen, Methoden, erforderlichen Scopes, Paginierungsregeln und Mutationsverträge im Überblick.
Alle öffentlichen Ressourcen, Methoden, erforderlichen Scopes, Paginierungsregeln und Mutationsverträge im Überblick.
Der maßgebliche maschinenlesbare Vertrag ist das OpenAPI JSON. Diese Seite ist der menschenlesbare Operationsindex und erklärt die Regeln, die für jeden Endpunkt gelten.
Basis-URL und Version#
https://makeagent.fast/api/v1Die Hauptversion ist Teil des Pfads. Zusätzliche Felder können ohne Änderung der Hauptversion hinzukommen. Ignorieren Sie daher unbekannte Felder in Antworten. Alle Management-Anfragen verwenden HTTPS sowie einen Bearer-API-Schlüssel oder ein OAuth-Zugriffstoken.
Gemeinsame Header#
Authorization: Bearer maf_live_...
Accept: application/json
Content-Type: application/json
Idempotency-Key: your-stable-operation-keyContent-Type ist für JSON-Bodys bei POST und PATCH erforderlich, auch bei {}. Idempotency-Key ist optional, wird aber für jedes POST, PATCH und DELETE dringend empfohlen.
Konto und Websites#
| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
GET | /me | account:read | Konto, Tarif, Berechtigungen und Wallet-Übersicht lesen |
GET | /sites | sites:read | Eigene Websites auflisten |
POST | /sites | sites:write | Eine Website und ihren Standard-Agent erstellen |
GET | /sites/{site_id} | sites:read | Eine eigene Website abrufen |
PATCH | /sites/{site_id} | sites:write | Unkritische Website-Felder aktualisieren |
DELETE | /sites/{site_id} | sites:write | Die Website und abhängige Ressourcen löschen |
POST | /sites/{site_id}/publish | sites:write | Mit { "published": boolean } veröffentlichen oder die Veröffentlichung aufheben |
GET | /sites/{site_id}/agent | agents:read | Agent-Einstellungen lesen |
PATCH | /sites/{site_id}/agent | agents:write | Persona-Modus, Zweck, Anzeigenamen, Anweisungen, Stimme, Sprachen, Modell, Erscheinungsbild, Einbettungsrahmen, Badge, Einbettungsstatus oder Origins aktualisieren |
GET | /sites/{site_id}/billing | account:read | Tarif, Abrechnungszeitraum, Wallet, Add-ons und die Abrechnungslinks im Dashboard lesen |
PATCH | /sites/{site_id}/workspace | team:write | Das Unternehmen umbenennen, dem der Agent gehört |
PATCH | /sites/{site_id}/retention | team:write | Festlegen, wie lange Unterhaltungen aufbewahrt werden |
Zum Erstellen einer Website sind title und content.headline erforderlich. Optionale Felder sind slug, type, template, zusätzliche Inhalte, persona_mode sowie ein bis vier Sprachen aus en, ko, uz und ru.
PATCH /agent führt model, appearance, embed_chrome und badge_hidden durch dieselben Tarifprüfungen wie das Dashboard; badge_hidden: true erfordert einen berechtigten Tarif oder das Badge-Add-on.
Installation und Website-Widget#
| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
GET | /sites/{site_id}/install | agents:read | Installationsziel, Einbettungsstatus, erlaubte Origins und Installationsnachweise lesen |
PATCH | /sites/{site_id}/install | agents:write | Die Seite festlegen, auf der das Widget installiert werden soll |
POST | /sites/{site_id}/install/check | agents:write | Prüfen, ob das Einbettungs-Snippet auf der Zielseite live ist |
Wissen und FAQs#
| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
GET | /sites/{site_id}/knowledge | knowledge:read | Wissensquellen auflisten |
POST | /sites/{site_id}/knowledge | knowledge:write | Eingefügten Text aufnehmen, eine Website crawlen oder eine YouTube-, Podcast- oder Feed-Quelle importieren |
PATCH | /sites/{site_id}/knowledge/{source_id} | knowledge:write | refresh_hours oder den approval_status des Buyer-Packs festlegen |
POST | /sites/{site_id}/knowledge/{source_id}/recrawl | knowledge:write | Erneutes Einlesen einer abgerufenen Quelle in die Warteschlange stellen; gibt 202 zurück |
DELETE | /sites/{site_id}/knowledge/{source_id} | knowledge:write | Eine Quelle aus dem künftigen Abruf entfernen |
GET | /sites/{site_id}/faqs | knowledge:read | Strukturierte FAQs auflisten |
POST | /sites/{site_id}/faqs | knowledge:write | { "question", "answer", "approved" } erstellen |
POST | /sites/{site_id}/faqs/generate | knowledge:write | FAQs aus dem Wissen des Agents entwerfen |
POST | /sites/{site_id}/faqs/approve-all | knowledge:write | Jede FAQ im Entwurfsstatus freigeben und veröffentlichen |
PATCH | /sites/{site_id}/faqs/{faq_id} | knowledge:write | Frage, Antwort oder Freigabestatus aktualisieren |
DELETE | /sites/{site_id}/faqs/{faq_id} | knowledge:write | Eine FAQ löschen |
GET / PATCH | /sites/{site_id}/fact-sheet | knowledge:read / knowledge:write | Das extrahierte Faktenblatt des Unternehmens lesen oder Fakten korrigieren, die bei der Extraktion falsch erkannt wurden |
POST | /sites/{site_id}/fact-sheet/reextract | knowledge:write | Die Website erneut einlesen und das Faktenblatt neu erstellen |
POST | /sites/{site_id}/qa | knowledge:write | Kuratierte Frage-Antwort-Paare veröffentlichen |
POST | /sites/{site_id}/answers/revise | knowledge:write | Dem Agent die Antwort beibringen, die er hätte geben sollen |
GET | /sites/{site_id}/knowledge-connections | knowledge:read | Wissensverbindungen zu Notion, Drive und MCP auflisten |
GET | /sites/{site_id}/knowledge-connections/connect-links | knowledge:read | Die Dashboard-URLs abrufen, die eine Notion- oder Drive-Verbindung starten |
PATCH / DELETE | /sites/{site_id}/knowledge-connections/{connection_id} | knowledge:write | Synchronisierungsintervall, ausgewählte Elemente oder Importwerkzeug festlegen; oder die Verbindung trennen und bereinigen |
GET | /sites/{site_id}/knowledge-connections/{connection_id}/items | knowledge:read | Die Seiten, Datenbanken oder Dateien auflisten, die eine Verbindung importieren kann |
POST | /sites/{site_id}/knowledge-connections/{connection_id}/sync | knowledge:write | Eine Synchronisierung einer Wissensverbindung in die Warteschlange stellen |
POST /knowledge akzeptiert drei Bodys: { "name", "text" } mit 5 bis 200.000 Zeichen; { "url", "max_pages", "refresh_hours" }, um eine Website zu crawlen (max_pages 1–40, refresh_hours 1–8.760 oder null); sowie { "kind": "youtube" | "podcast" | "feed", "url", "refresh_hours" }. YouTube-, Podcast- und Feed-Quellen erfordern Operate oder Scale; bei Launch geben sie 409 conflict zurück. Der Datei-Upload bleibt ein Dashboard-Workflow.
Unterhaltungen, Leads, Analysen und Nutzung#
| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
GET | /sites/{site_id}/conversations | conversations:read | Unterhaltungsverläufe auflisten |
GET | /sites/{site_id}/conversations/{conversation_id} | conversations:read | Einen Verlauf und paginierte Nachrichten abrufen |
POST | /sites/{site_id}/conversations/{conversation_id}/reply | conversations:write | Einem Besucher im Namen des Unternehmens antworten |
POST | /sites/{site_id}/conversations/{conversation_id}/pause | conversations:write | Den Agent in dieser Unterhaltung pausieren und sie übernehmen |
POST | /sites/{site_id}/conversations/{conversation_id}/resume | conversations:write | Die Unterhaltung an den Agent zurückgeben |
GET | /sites/{site_id}/leads | leads:read | Erfasste Leads auflisten |
POST | /sites/{site_id}/leads | leads:write | Einen kanonischen Lead mit ausdrücklicher Einwilligung und Kontaktpräferenzen erstellen |
GET | /sites/{site_id}/leads/{lead_id} | leads:read | Einen Lead abrufen |
PATCH | /sites/{site_id}/leads/{lead_id} | leads:write | Einen Lead aktualisieren, qualifizieren oder seine Kontaktrichtlinie ändern |
POST | /sites/{site_id}/leads/{lead_id}/accept | leads:write | Einen Lead in die Opportunity-Pipeline übernehmen |
POST | /sites/{site_id}/leads/{lead_id}/followup | leads:write | Die Folgenachricht an einen Lead senden |
POST | /sites/{site_id}/leads/{lead_id}/followup/draft | leads:write | Die Folgenachricht neu entwerfen, ohne sie zu senden |
GET | /sites/{site_id}/analytics | analytics:read | Analyseereignisse auflisten |
GET | /sites/{site_id}/report | analytics:read | Den aggregierten Analysebericht lesen |
POST | /sites/{site_id}/report/unanswered-faq | knowledge:write | Eine unbeantwortete Frage als neue FAQ beantworten |
GET | /sites/{site_id}/usage | usage:read | Gemessene Nutzungsereignisse auflisten |
Diese Ereignis- und Aktivitätssammlungen akzeptieren limit und cursor. Zurückgegebene Datensätze können personenbezogene Daten enthalten; speichern und exportieren Sie sie gemäß Ihren Datenschutzpflichten.
Antworten des Owners werden unterstützt: reply, pause und resume übernehmen einen Web-Verlauf oder einen Chat auf Telegram, WhatsApp, Messenger oder Instagram auf dieselbe Weise wie das Dashboard. Das Senden von Nachrichten als Besucher ist keine öffentliche API-Operation.
Die Änderung von Leads wird unterstützt; setzen Sie consent_status: granted nur, wenn Ihr System
über einen belastbaren Einwilligungsnachweis verfügt. Unbekannte Einwilligungen werden von Broadcasts ausgeschlossen.
Opportunity-Pipeline und CRM-Ergebnisse#
| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
GET / POST | /sites/{site_id}/pipeline/stages | pipeline:read / pipeline:write | Phasen auflisten oder konfigurieren |
GET / POST | /sites/{site_id}/pipeline/accounts | pipeline:read / pipeline:write | Geschäftskonten auflisten oder erstellen |
GET | /sites/{site_id}/pipeline/accounts/{account_id} | pipeline:read | Ein Geschäftskonto abrufen |
GET / POST | /sites/{site_id}/pipeline/opportunities | pipeline:read / pipeline:write | Opportunities auflisten oder erstellen |
GET / PATCH | /sites/{site_id}/pipeline/opportunities/{opportunity_id} | pipeline:read / pipeline:write | Aktivitäten lesen oder Zuweisung, Wert, Phase, nächste Aktion und menschliche Antwort aktualisieren |
POST | /sites/{site_id}/pipeline/outcomes | pipeline:write | Ein aus dem CRM stammendes Ergebnis (gewonnen oder verloren) idempotent importieren |
GET | /sites/{site_id}/pipeline/sync-records | pipeline:read | Synchronisierungsstatus, Versuche und Fehler auflisten |
POST | /sites/{site_id}/pipeline/sync-records/{sync_record_id}/retry | pipeline:write | Ein fehlgeschlagenes Ergebnis anhand seiner gespeicherten Nutzdaten erneut versuchen |
GET / PATCH | /sites/{site_id}/pipeline-workflow | pipeline:read / pipeline:write | Die Vertriebsantwort-Richtlinie lesen oder aktualisieren |
GET / POST | /sites/{site_id}/pilots | pipeline:read / pipeline:write | Geführte Pilotprojekte auflisten oder starten |
GET | /sites/{site_id}/pilots/{pilot_id} | pipeline:read | Ein Pilotprojekt, seine Phase, Zählwerte und Arbeitsliste lesen |
POST | /sites/{site_id}/pilots/{pilot_id}/setup, /start, /stop, /review, /decision, /complete, /delete | pipeline:write | Ein Pilotprojekt durch Einrichtung, Messung, Review, Entscheidung und Abschluss führen oder es samt Nachweisen löschen (sieben Operationen) |
POST | /sites/{site_id}/pilots/{pilot_id}/outcomes, /bookings | pipeline:write | Ein Lead-Ergebnis oder ein Buchungsergebnis erfassen (zwei Operationen) |
POST | /sites/{site_id}/pilots/{pilot_id}/report/approve, /report/revoke | pipeline:write | Den teilbaren Pilotbericht freigeben oder die Freigabe widerrufen (zwei Operationen) |
GET / POST | /sites/{site_id}/buyer-packs | pipeline:read / pipeline:write | Buyer-Packs auflisten oder eines aus freigegebenen Quellen erstellen |
PATCH | /sites/{site_id}/buyer-packs/{pack_id} | pipeline:write | Titel, Zielgruppe, Zusammenfassung, Quellen und Abschnitte eines Packs ersetzen |
POST | /sites/{site_id}/buyer-packs/{pack_id}/approve, /revoke | pipeline:write | Den Freigabelink des Packs aktivieren oder deaktivieren (zwei Operationen) |
Der angegebene CRM-provider, die externe ID und der Idempotenzschlüssel bleiben im Audit-Trail
erhalten. Ein Retry übernimmt nur einen fehlgeschlagenen Datensatz und macht aus einem laufenden
externen Schreibvorgang niemals einen fälschlichen Erfolg.
Connectors#
| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
GET | /sites/{site_id}/connectors | connectors:read | Connector-Status ohne Geheimnisse auflisten |
POST | /sites/{site_id}/connectors | connectors:write | Einen Kanal verbinden: Zugangsdaten live validieren, den Webhook bereitstellen und die Einrichtungs-Checkliste zurückgeben |
PATCH | /sites/{site_id}/connectors/{connector_id} | connectors:write | status oder reply_with_voice festlegen |
DELETE | /sites/{site_id}/connectors/{connector_id} | connectors:write | Einen Connector deprovisionieren und entfernen |
POST | /sites/{site_id}/concierge | connectors:write | Die Plattform bitten, einen Messaging-Kanal für Sie zu verbinden |
GET | /sites/{site_id}/domains | domains:read | Entfernt – gibt 409 zurück. Eigene Domains werden nicht angeboten |
POST | /sites/{site_id}/domains | domains:write | Entfernt – gibt 409 zurück |
PATCH | /sites/{site_id}/domains/{domain_id} | domains:write | Entfernt – gibt 409 zurück |
POST | /sites/{site_id}/domains/{domain_id}/verify | domains:write | Entfernt – gibt 409 zurück |
DELETE | /sites/{site_id}/domains/{domain_id} | domains:write | Entfernt – gibt 409 zurück |
Die Erstellung eines Connectors verwendet einen nach Kanal unterschiedenen Body. Die Felder für Zugangsdaten unterscheiden sich bei telegram, whatsapp, messenger, instagram, discord und kakao; verwenden Sie die passende Connector-Anleitung, bevor Sie Geheimnisse senden.
Broadcasts, Benachrichtigungen und Monetarisierung#
| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
GET | /sites/{site_id}/broadcasts | broadcasts:read | Broadcasts auflisten |
POST | /sites/{site_id}/broadcasts | broadcasts:write | Einen Kakao-Broadcast-Entwurf erstellen |
POST | /sites/{site_id}/broadcasts/{broadcast_id}/send | broadcasts:write | Einen vorhandenen Entwurf in die Warteschlange stellen; gibt 202 zurück |
GET | /sites/{site_id}/notifications | notifications:read | Owner-Benachrichtigungen auflisten |
POST | /sites/{site_id}/notifications/read-all | notifications:write | Jede Owner-Benachrichtigung für diesen Agent als gelesen markieren |
PATCH | /sites/{site_id}/notifications/{notification_id} | notifications:write | Mit { "read": boolean } als gelesen oder ungelesen markieren |
GET | /sites/{site_id}/alerts | notifications:read | Den Status des Alarmkanals des Owners und seinen Dashboard-Link lesen |
GET | /sites/{site_id}/monetization/products | monetization:read | Website-Produkte auflisten |
POST | /sites/{site_id}/monetization/products | monetization:write | Ein Produkt vom Typ access, consult, tip oder digital erstellen |
PATCH | /sites/{site_id}/monetization/products/{product_id} | monetization:write | Produktfelder und aktiven Status aktualisieren |
DELETE | /sites/{site_id}/monetization/products/{product_id} | monetization:write | Ein Produkt löschen |
Die Erstellung von Broadcasts akzeptiert derzeit nur den Kanal kakao. Das Einreihen in die Warteschlange schlägt mit 409 conflict fehl, wenn es keine erreichbaren Empfänger gibt oder der Broadcast kein Entwurf mehr ist.
Aktionen, Tickets und Team#
| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
GET / PATCH | /sites/{site_id}/actions | agents:read / agents:write | Prozeduren, den öffentlichen Webhook, den Buchungslink und Support-Tickets lesen oder konfigurieren |
GET | /sites/{site_id}/tickets | tickets:read | Support-Tickets auflisten |
GET | /sites/{site_id}/tickets/{ticket_id} | tickets:read | Ein Ticket und seine Nachrichten lesen |
PATCH | /sites/{site_id}/tickets/{ticket_id} | tickets:write | Status, Priorität und optional die zuständige Person festlegen |
POST | /sites/{site_id}/tickets/{ticket_id}/messages | tickets:write | Eine interne Notiz hinzufügen oder mit internal: false dem Kunden per E-Mail antworten |
GET | /sites/{site_id}/team | team:read | Mitglieder, Einladungen und zulässige Audit-Ereignisse lesen |
POST | /sites/{site_id}/team/invitations | team:write | Einen Einladungslink erstellen, ohne eine E-Mail zu senden |
DELETE | /sites/{site_id}/team/invitations/{invitation_id} | team:write | Eine ausstehende Einladung widerrufen |
PATCH / DELETE | /sites/{site_id}/team/members/{membership_id} | team:write | Die Rolle eines Mitglieds, das nicht Owner ist, ändern oder das Mitglied entfernen |
Entwickler-Webhooks und Einrichtungswerkzeuge#
| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
GET | /webhook-endpoints | webhooks:read | Endpunktstatus ohne Signaturgeheimnisse auflisten |
POST | /webhook-endpoints | webhooks:write | Eine öffentliche HTTPS-URL registrieren und ihr Signaturgeheimnis einmalig anzeigen |
DELETE | /webhook-endpoints/{endpoint_id} | webhooks:write | Einen Endpunkt löschen und die künftige Zustellung stoppen |
GET | /setup/tools | Beliebige gültige Zugangsdaten | Einrichtungswerkzeuge für API-, MCP- und GitHub-Integrationen ermitteln |
POST | /setup/tools/{tool_name} | Werkzeugspezifisch | Ein Einrichtungswerkzeug ausführen; Plattformanfragen benötigen die Scopes ihrer Endpunkte, die GitHub-Prüfung verwendet integrations:read, die PR-Vorbereitung integrations:write |
Webhook-URLs müssen HTTPS verwenden, dürfen keine Zugangsdaten und keinen benutzerdefinierten Port enthalten und müssen ausschließlich auf öffentliche IP-Adressen auflösen.
Paginierung#
Paginierte Sammlungen akzeptieren limit von 1 bis 100; der Standardwert ist 50. Verwenden Sie den zurückgegebenen undurchsichtigen next_cursor nur mit derselben Sammlung und denselben Filtern.
{
"data": [],
"has_more": false,
"next_cursor": null
}Einige kleine Konfigurationssammlungen geben dieselbe Hülle mit has_more: false zurück und benötigen keinen Cursor.
Idempotenz#
Ein Idempotenzschlüssel muss 8 bis 200 Zeichen enthalten: Buchstaben, Ziffern sowie ., _, : und -. Ergebnisse werden 24 Stunden lang aufbewahrt und gelten für den Inhaber der Zugangsdaten.
- Gleicher Schlüssel und gleiche Methode, gleicher Pfad, gleiche Query und gleicher Body: gibt die gespeicherte Antwort mit
x-idempotent-replayed: truezurück. - Gleicher Schlüssel mit anderer Eingabe: gibt
409 conflictzurück. - Gleicher Schlüssel, während die erste Anfrage noch verarbeitet wird: gibt
409 conflictundRetry-After: 2zurück.
Speichern Sie den Schlüssel, bevor Sie die Mutation senden, und verwenden Sie ihn nur für Wiederholungen derselben logischen Operation erneut.
Antworten und Fehler#
Erfolgreiche Antworten verpacken ihre Ressource in data. Erstellungsoperationen geben normalerweise 201 zurück; in die Warteschlange gestellte Broadcast-Sendungen geben 202 zurück; andere erfolgreiche Operationen geben 200 zurück. Jede Antwort enthält x-request-id und verwendet für API-Daten Cache-Control: no-store.
Die vollständige Tabelle der Fehlercodes finden Sie unter Scopes und Fehler, kopierbare Workflows unter API-Rezepte.
MCP-Clients#
Verbinden Sie einen Streamable-HTTP-MCP-Client mit https://makeagent.fast/api/mcp. Clients, die OAuth Discovery unterstützen, öffnen den Browser für Anmeldung und Einwilligung. Prüfen Sie vor der Freigabe die Identität des Clients, das Unternehmen und die angeforderten Scopes. Die erste Freigabe fragt die Scopes ab, die die Tools verwenden (sites:read, sites:write, agents:write, analytics:read, conversations:read, conversations:write, leads:read, leads:write, knowledge:write); bei Zugangsdaten, denen einer dieser Scopes fehlt, wird erneut um Autorisierung gebeten. Ein aktiver Tarif ist erforderlich.
Für Clients mit manuell konfigurierten Zugangsdaten erstellen Sie in den Entwicklereinstellungen einen API-Schlüssel mit begrenzten Scopes und übergeben ihn als Header Authorization: Bearer .... Halten Sie Zugangsdaten aus der Versionsverwaltung und aus Browsercode heraus. API-Schlüssel oder OAuth-Berechtigungen widerrufen Sie in den Entwicklereinstellungen.
Lese-Tools: list_agents, get_agent, get_report, list_unanswered_questions, list_conversations, get_conversation, list_leads. Schreib-Tools: create_agent_from_website, create_agent_from_notes, test_agent, add_knowledge, save_answer, reply_to_customer, update_lead, set_website_widget. Jedes Agent-Tool erwartet eine agent_id aus list_agents. test_agent verbraucht Credits wie eine normale Antwort; reply_to_customer sendet eine Nachricht an den Kunden und pausiert den Agent in dieser Unterhaltung; set_website_widget schaltet das Website-Chat-Widget ein oder aus; Messaging-Kanäle werden im Dashboard verwaltet. Clients mit aktivierten MCP Apps (standardmäßig die authentifizierte Claude-Verbindung) erhalten außerdem list_pending_approvals, list_action_runs und decide_approval, womit eine vom Kunden bestätigte Änderung genehmigt oder abgelehnt wird; andere Clients sehen nur die 15 oben genannten Tools. Für die Einrichtungs- und GitHub-Integrationstools verwenden Sie den In-App-Einrichtungsassistenten oder /api/v1/setup/tools.
Unterstützte Protokollrevisionen sind 2026-07-28, 2025-11-25 und 2025-06-18. Der Transport liefert JSON; ältere SSE-Varianten oder Server-Sitzungen werden nicht angeboten. MCP-OAuth-Tokens autorisieren nur /api/mcp, nicht direkte REST-Anfragen. OAuth-Zugriffstokens sind eine Stunde gültig; Refresh-Zugangsdaten werden rotiert und laufen nach 90 Tagen ab. Manuell erstellte API-Schlüssel verwenden ihr konfiguriertes Ablaufdatum.