API-Rezepte

Diese Rezepte verwenden rohes REST und funktionieren daher, bevor ein öffentliches SDK installiert ist. Legen Sie MAF_API_KEY in der Server-Umgebung fest und ersetzen Sie die IDs, die in früheren Schritten zurückgegeben wurden.

Rezept: Einen fundierten Agent erstellen und veröffentlichen#

Erstellen Sie einen API-Schlüssel mit sites:write, agents:write und knowledge:write. Fügen Sie sites:read hinzu, wenn die Automatisierung auch Websites auflistet oder überprüft.

1. Die Website erstellen#

curl --fail-with-body https://makeagent.fast/api/v1/sites \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-site-2026-01" \
  -d '{
    "title": "Acme support",
    "slug": "acme-support",
    "type": "business",
    "template": "minimal",
    "content": {
      "headline": "Ask Acme support"
    },
    "persona_mode": "assistant",
    "languages": ["en"]
  }'

Eine erfolgreiche Antwort lautet 201 Created, enthält die Website unter data und gibt ihren kanonischen Ressourcenpfad im Location-Header zurück. Speichern Sie data.id als SITE_ID.

2. Den Agent und die Embed-Richtlinie konfigurieren#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-agent-2026-01" \
  -d '{
    "display_name": "Acme guide",
    "persona_mode": "assistant",
    "instructions": "Answer only from confirmed Acme sources. If the answer is missing, say that a teammate will follow up.",
    "languages": ["en"],
    "embed_enabled": true,
    "allowed_origins": ["https://www.acme.example", "https://staging.acme.example"]
  }'

Erlaubte Origins sind exakte Origins: Schema, Hostname und optional ein Port. Geben Sie keinen Pfad und keinen abschließenden Platzhalter an.

3. Eine Text-Quelle hinzufügen#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/knowledge" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-returns-2026-01" \
  -d '{
    "name": "Returns policy 2026-01",
    "text": "Customers may request a return within 30 days of delivery. Contact support before sending an item back."
  }'

Eingefügter Text muss zwischen 5 und 200.000 Zeichen lang sein. Derselbe Endpunkt kann auch eine Website mit { "url", "max_pages", "refresh_hours" } crawlen (max_pages bis zu 40) oder { "kind": "youtube" | "podcast" | "feed", "url" } importieren. Diese Medien-Quellen erfordern Operate oder Scale und liefern bei Launch 409 zurück. Datei-Uploads sind weiterhin nur im Dashboard möglich.

4. Ein strukturiertes FAQ hinzufügen#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/faqs" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-faq-returns-2026-01" \
  -d '{
    "question": "How long do I have to return an order?",
    "answer": "You may request a return within 30 days of delivery.",
    "approved": true
  }'

5. Veröffentlichen#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/publish" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-publish-2026-01" \
  -d '{"published": true}'

Die Antwort sollte {"data":{"id":"...","status":"published"}} enthalten. Öffnen Sie ein echtes Embed und stellen Sie eine Frage, deren Antwort in der Quelle steht. Die Veröffentlichung belegt, dass sich der Zustand des Agents geändert hat; sie belegt nicht, dass die Qualität der Quelle oder der Embed-Origin korrekt ist.

Rezept: Leads sicher paginieren#

Verwenden Sie einen Schlüssel mit leads:read. Behandeln Sie next_cursor als opak und kodieren Sie ihn per URL-Encoding.

const base = `https://makeagent.fast/api/v1/sites/${siteId}/leads`;
let cursor: string | null = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
  });
  if (!response.ok) throw await response.json();

  const page = await response.json();
  for (const lead of page.data) await exportLead(lead);
  cursor = page.next_cursor;
} while (cursor);

Dekodieren, bearbeiten oder sortieren Sie einen Cursor nicht und verwenden Sie ihn nicht für eine andere Collection.

Rezept: Ein Embed bei einem Vorfall deaktivieren#

Verwenden Sie agents:write und behalten Sie bei Netzwerk-Wiederholungen denselben Idempotency-Key bei:

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-07-embed-off" \
  -d '{"embed_enabled": false}'

Prüfen Sie nach der erfolgreichen Antwort, dass sich der Launcher auf einem erlaubten Host nicht mehr initialisiert. Aktivieren Sie ihn mit einem neuen Schlüssel für die Vorfallbehebung wieder, nachdem Sie das Problem mit dem Origin, dem Inhalt oder den Zugangsdaten behoben haben.

Checkliste für die Produktion#

• Verwenden Sie pro Dienst und Umgebung einen eigenen Schlüssel.
• Speichern Sie Ressourcen-IDs und Idempotency-Keys, bevor Sie eine Mutation senden.
• Legen Sie Timeouts für Verbindungsaufbau und Antwort fest.
• Beachten Sie Retry-After und begrenzen Sie die Anzahl der Wiederholungen.
• Protokollieren Sie Operationsname, HTTP-Status und Request-ID, ohne Secrets oder personenbezogene Daten zu protokollieren.
• Testen Sie mit einer Nicht-Produktions-Website, bevor Sie Schreibberechtigungen für die Produktion vergeben.