API-Schnellstart

Dieser Schnellstart prüft, ob sich ein Backend authentifizieren und Ihr Konto lesen kann. Sie benötigen einen aktiven kostenpflichtigen Tarif, ein Terminal mit curl und Zugriff auf Dashboard → Einstellungen → Entwickler.

Die aktuelle v1-API verwaltet und synchronisiert Ressourcen. Sie ist kein Transportweg für benutzerdefinierte Chats: Sie können keine Nachrichten als Besucher senden. Leads können erstellt, aktualisiert und akzeptiert werden (leads:write), und ein Owner kann auf eine Konversation antworten sowie sie pausieren oder fortsetzen (conversations:write).

1. Einen Schlüssel mit minimalen Berechtigungen erstellen#

Erstellen Sie einen Schlüssel mit dem Namen Local API quickstart, wählen Sie account:read und sites:read aus und legen Sie ein kurzes Ablaufdatum fest. Kopieren Sie den Klartextschlüssel sofort; er wird nicht noch einmal angezeigt.

Verwenden Sie keinen Schlüssel eines KI-Anbieters, etwa von OpenRouter oder Speko. Die öffentliche API erfordert einen Make-Agent-Fast-Schlüssel, der mit maf_live_ beginnt.

2. Für dieses Terminal speichern#

export MAF_API_KEY="maf_live_..."

Prüfen Sie, ob die Variable existiert, ohne das Geheimnis auszugeben:

test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"

Committen Sie den Schlüssel nicht in .env, in Beispiele mit Shell-Verlauf, Test-Fixtures oder ein Browser-Bundle. Verwenden Sie für bereitgestellten Code den Secret Manager Ihres Hosts.

3. Das Konto abfragen#

curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Erwarteter Status: 200 OK. Der Body enthält data.id, Informationen zu Tarif und Berechtigungen sowie eine Wallet-Zusammenfassung. Die Antwort enthält außerdem x-request-id; bewahren Sie diesen Wert auf, wenn Sie eine fehlgeschlagene Anfrage melden.

{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "owner@example.com",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}

Felder können hinzukommen, ohne dass sich der Pfad /v1 ändert. Ignorieren Sie unbekannte Felder, anstatt die Antwort abzulehnen.

4. Websites auflisten#

curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Antworten für Sammlungen verwenden dieses Format:

{
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Wenn has_more den Wert true hat, senden Sie den exakten Wert von next_cursor als Query-Parameter cursor der nächsten Anfrage. Dekodieren oder konstruieren Sie Cursor nicht selbst.

5. Einen strukturierten Fehler behandeln#

Entfernen Sie vorübergehend den Authorization-Header und wiederholen Sie /me. Die Antwort sollte 401 mit einem stabilen Code lauten:

{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}

Produktionscode sollte anhand von error.code verzweigen und nicht message vergleichen. Protokollieren Sie die Operation, den HTTP-Status und die Request-ID, jedoch nicht den Schlüssel.

6. Den ersten Schreibzugriff sicher durchführen#

Erstellen Sie einen separaten Schlüssel, der zusätzlich sites:write, agents:write und knowledge:write enthält; erweitern Sie nicht den Lese-Schlüssel des Schnellstarts. Folgen Sie den API-Rezepten, um eine Website zu erstellen, fundiertes Wissen hinzuzufügen und sie mit expliziten Idempotenzschlüsseln zu veröffentlichen.

Häufige Fehler bei der ersten Anfrage#

Fahren Sie fort mit Scopes und Fehler, der API-Referenz und den Rate Limits.