API und Agenten
Nutze OAuth, entdecke aktuelle OpenAPI-Verträge und behandle Fehler in API und MCP.
Leadbase stellt einen gemeinsamen Operationskatalog über die öffentliche HTTP-API, MCP und den App-Assistenten bereit. Dieselben Rechte, Änderungsversionen, Credit-Prüfungen und Wiederholungsregeln gelten für alle Zugänge.
Beginne für einen KI-Client mit der MCP-Einrichtung oder verwende die HTTP-API für deine eigene Integration. Externer Zugriff benötigt neben der Autorisierung auch die passende API-Berechtigung des Workspace-Tarifs.
Mit OAuth authentifizieren
Nutze den Autorisierungsserver aus den Metadaten der geschützten Ressource. Die öffentliche API-Ressource ist dein Leadbase-Origin mit /api; die MCP-Ressource ist derselbe Origin mit /api/mcp. Tokens sind an ihre Audience gebunden: Ein MCP-Token kann nicht für die HTTP-API verwendet werden.
Ressourcenmetadaten stehen unter /.well-known/oauth-protected-resource/api und /.well-known/oauth-protected-resource/api/mcp. Ohne Token kommt eine 401-Challenge mit einer Ressourcenmetadaten-URL zurück. Hole über OAuth ein Token für die gewünschte Ressource und sende es im Authorization-Header; verwende weder ein App-Session-Cookie noch einen Anbieter-API-Schlüssel als Ersatz.
Fordere mcp:read für Lesen und mcp:write für autorisierte Änderungen oder kostenpflichtige Operationen an. Letzteres erlaubt auch Lesen. Mitgliedschaft, Ressourcenrechte und Tarifberechtigung werden bei jeder Ausführung geprüft.
Den aktuellen Vertrag entdecken
Alle drei folgenden GET-Endpunkte brauchen API-Autorisierung und liefern einen nach deinen Scopes gefilterten Katalog:
Verwende IDs mit Punkten, etwa sheets.get. MCP verwendet zugehörige Namen wie sheets_get. Native Schemas erzeugen die veröffentlichten Verträge; nutze sie für generierte Client-Typen und Eingabeprüfung. Laufzeitprüfung von Rechten und fachlichen Regeln bleibt erforderlich.
Sende einen unkomprimierten application/json-Body; die Grenze ist 1 MiB. Halte dich genau an das aktuelle Schema, einschließlich erforderlicher Felder mit explizitem null, soweit erlaubt. Leite Eingaben nicht aus alten Beispielen oder dem Anzeigenamen eines Tools ab.
Ein Sheet lesen
Der JSON-Body für POST /api/v1/operations/sheets.get lautet:
Die ID ist beispielhaft; verwende ein Sheet, auf das du zugreifen kannst. Die Antwort enthält Spalten und Metadaten einschließlich Versionen. Weiter geht es mit Sheet-Lesezugriff und Änderungen.
Ergebnisse, Fehler und Wiederaufnahme
Bei HTTP-Erfolg kommt das fachliche Ergebnis der Operation zurück. HTTP-Fehler enthalten üblicherweise ein error-Objekt mit code und message; Authentifizierungsfehler haben eine eigene OAuth-Fehlerantwort. MCP-Fehler setzen isError und liefern strukturiert Code, Meldung und Status. Erfolgreiche MCP-Inhalte stehen in structuredContent.
Eine 200-Antwort kann bei Kontaktsuche status: "failed" oder not_found enthalten. Sie bedeutet nicht, dass alle Anbieter funktionieren. IDEMPOTENCY_PENDING und AMBIGUOUS_OUTCOME bedeuten, dass du die ursprüngliche Anfrage wiederaufnehmen musst, statt eine neue logische Operation zu starten.
Jede neue Änderung oder kostenpflichtige Anfrage braucht einen eigenen idempotencyKey. Verwende exakt denselben Schlüssel und Body nur zur Wiederaufnahme dieser Anfrage. Speichere die Operations-, Changeset-, Anfrage- oder Lauf-IDs des jeweiligen Ergebnisschemas. Interne Anbieterfehler werden von der öffentlichen API absichtlich nicht im Wortlaut ausgegeben.
Siehe Kontaktsuche, Prospect-Suche, MCP Apps und Ereignisse und Credits.