Zum Inhalt springen

API & KI-Agenten

API-Schlüssel in den Einstellungen erzeugen

Lass deine eigenen Programme — oder einen KI-Agenten wie Claude, Cursor oder Gemini — öffentliche Pins von Fruit Pin lesen und deine eigenen Pins und Fotos verwalten. Die API folgt denselben Regeln wie die App: Fotos durchlaufen dieselbe Entfernung von Standort- und Kameradaten, Beiträge dieselben Prüfungen, den Privacy Mode und die Moderation.

REST-API https://fruitpin.com/api/v1 · OpenAPI 3.1
MCP-Server https://fruitpin.com/mcp (Streamable HTTP)
Anmeldung Authorization: Bearer fp_live_…
Für wen jedes Fruit-Pin-Konto; Schreiben braucht einen bestätigten Nutzernamen
Anfragelimit 60 Anfragen pro Minute je Schlüssel, 120 je Konto (REST und MCP zusammen)

Was Fruit Pin ist — und was nicht

Fruit Pin zeigt Orte. Es ist keine Bestimmungshilfe und gibt keine Verzehrempfehlung. Viele Pflanzen haben Doppelgänger; nur du kannst eine Pflanze sicher bestimmen, und du trägst die Verantwortung für das, was du sammelst. Dein KI-Agent bekommt diese Regeln bei jeder Verbindung mit und soll dich darauf hinweisen — prüfe seine Antworten trotzdem.

Pins anderer Nutzer liefert die API ohne Foto-Adressen: mit Ort, Art, Zugangsart und einem Link auf die Seite des Pins in Fruit Pin (web_url), wo die Fotos zu sehen sind. Deine eigenen Fotos bekommst du mit Adresse. Fasse Pins derselben Person nicht zu einem Profil zusammen (Nutzungsbedingungen 6.9).

1. API-Schlüssel erzeugen

Öffne in der App Profil → Einstellungen → API & KI-Agenten, gib dem Schlüssel einen Namen (zum Beispiel den des Agenten, der ihn nutzt) und wähle die Berechtigungen:

Berechtigung Erlaubt
Lesen öffentliche Pins suchen, Arten lesen, eigene Pins und Fotos auflisten
Schreiben Pins mit Foto anlegen, Fotos hinzufügen, Positionen korrigieren, eigene Pins und Fotos löschen, Profilnamen verbergen oder zeigen

Der Schlüssel wird einmal angezeigt. Wir speichern nur einen Fingerabdruck (SHA-256) davon und können ihn nicht wieder anzeigen; geht er verloren, widerrufe ihn und erzeuge einen neuen. Ein Widerruf wirkt ab der nächsten Anfrage. Ein Konto kann 10 aktive Schlüssel haben. Zum Erzeugen fragen wir nach deinem Passwort, wenn deine Anmeldung länger als zehn Minuten her ist. Änderst du dein Passwort, werden alle Schlüssel widerrufen.

Schreiben setzt einen bestätigten Nutzernamen voraus. Fotos über die API brauchen außerdem die Bildregeln von Fruit Pin, einmal in der App bestätigt (beim Anlegen eines Pins dort oder mit dem Häkchen beim Schlüssel).

Behandle einen Schlüssel wie ein Passwort: Er handelt in deinem Namen. Er gehört nicht in Code-Repositories oder Chatverläufe.

2. Mit deinem KI-Agenten verbinden (MCP)

Der MCP-Server gibt einem KI-Agenten Werkzeuge wie search_spots, get_spot, list_species, create_spot, add_photo, move_my_spot, delete_my_photo und delete_my_spot. Der Agent sieht nur die Werkzeuge, die sein Schlüssel nutzen darf.

Claude Code

claude mcp add --transport http fruitpin https://fruitpin.com/mcp \
  --header "Authorization: Bearer fp_live_…"

Cursor, VS Code und andere Programme mit JSON-Einstellungen

{ "mcpServers": { "fruitpin": { "url": "https://fruitpin.com/mcp", "headers": { "Authorization": "Bearer fp_live_…" } } } }

Claude Desktop (über die Brücke mcp-remote)

{ "mcpServers": { "fruitpin": { "command": "npx", "args": ["mcp-remote", "https://fruitpin.com/mcp", "--header", "Authorization: Bearer fp_live_…"] } } }

Gemini CLI (~/.gemini/settings.json)

{ "mcpServers": { "fruitpin": { "httpUrl": "https://fruitpin.com/mcp", "headers": { "Authorization": "Bearer fp_live_…" } } } }

Dann frag zum Beispiel: „Welche Pins mit Walnussbäumen gibt es im Umkreis von 2 km um den Bonner Hauptbahnhof?" oder „Leg für den Mirabellenbaum auf diesem Foto einen Pin bei 50.7341, 7.0982 an — frag mich, bevor du die Bildregeln bestätigst."

Programme, die sich nur über einen OAuth-Ablauf ohne eigene Kopfzeile verbinden, können sich noch nicht verbinden.

3. Schnellstart mit curl

Öffentliche Pins im Umkreis von 1 km suchen:

curl "https://fruitpin.com/api/v1/spots?lat=50.7341&lng=7.0982&radius_m=1000" \
  -H "Authorization: Bearer fp_live_…"

Einen Pin mit Foto anlegen (das Foto ist Pflicht; no_persons_confirmed muss true sein):

curl https://fruitpin.com/api/v1/me/spots \
  -H "Authorization: Bearer fp_live_…" \
  -H "Idempotency-Key: mirabelle-2026-11-01" \
  -F photo=@baum.jpg \
  -F 'metadata={"species_id":"sp-mirabelle","lat":50.7341,"lng":7.0982,"access_type":"oeffentlich","access_note":"Rand des Wiesenwegs","no_persons_confirmed":true}'

Die Art-IDs liefert /api/v1/species. Schick nach einer Zeitüberschreitung denselben Idempotency-Key noch einmal: Du bekommst die erste Antwort zurück statt eines zweiten Pins.

4. Regeln für Beiträge

  • Fotos: JPEG, höchstens 8 MB. Standort- und Kameradaten werden entfernt, bevor ein Foto öffentlich wird; ein Foto, bei dem das nicht gelingt, wird abgelehnt und nicht gespeichert.
  • Bildregeln: Jedes Foto braucht no_persons_confirmed: true — keine erkennbaren Personen, keine Kfz-Kennzeichen, keine Hausnummern oder Klingelschilder. Ein Agent muss dich fragen, bevor er das bestätigt.
  • Arten: nur Arten aus /api/v1/species. Pilze gehören nicht zu Fruit Pin. Bei Arten mit Verwechslungshinweis sagt species_note_confirmed: true, dass du den Hinweis gelesen und die Art selbst sicher bestimmt hast.
  • Dubletten: Gibt es im Umkreis von 50 m schon einen Pin derselben Art, kommt 409 possible_duplicate mit seiner ID. Füg dein Foto dort hinzu oder leg mit allow_nearby: true trotzdem einen eigenen Pin an.
  • Privacy Mode (voreingestellt an): Neue Pins und Fotos werden für andere am nächsten Morgen um 6:00 Uhr (deutsche Zeit) sichtbar, der mindestens 24 Stunden nach dem Hochladen liegt.
  • Positionen sind öffentlich. Setze keine Pins an deiner eigenen Wohnadresse. Wähle access_type ehrlich: oeffentlich (öffentlicher Grund), freigegeben (der Eigentümer erlaubt den Zugang) oder unklar.
  • Sammeln: nur in geringen Mengen für den eigenen Bedarf, pfleglich und nur, wo Betreten erlaubt ist (Handstraußregel).
  • Ändern und Löschen: Ein Pin lässt sich höchstens 50 m von der Stelle verschieben, an der er angelegt wurde. Während einer Prüfung durch die Moderation lassen sich Pins und Fotos weder ändern noch löschen; ein Pin mit Fotos anderer lässt sich nicht löschen, und das einzige Foto deines Pins geht nur zusammen mit dem Pin.

5. Grenzen und Fehler

Grenze Wert
Anfragen 60 pro Minute je Schlüssel, 120 pro Minute je Konto
Neue Pins 20 in 24 Stunden
Fotos 40 in 24 Stunden
Änderungen (Position, Profilname) 60 in 24 Stunden
Löschungen 30 in 24 Stunden
Suchgebiet Umkreis bis 10 km oder Rechteck bis 0,5° je Seite
Seitengröße bis 100, weiter mit next_cursor

Fehler kommen als JSON: { "error": "daily_limit_exceeded", "message": "…" }. Eine 429 trägt Retry-After. Inhalte anderer Konten beantwortet die API mit 404 — sie verrät nicht, ob es sie gibt.

6. Was wir speichern

Von einem Schlüssel: seinen Namen, die ersten 14 Zeichen, einen Fingerabdruck (SHA-256), die Berechtigungen und wann er erzeugt, zuletzt benutzt und widerrufen wurde. Nach einer fehlgeschlagenen Anmeldung behalten wir einen Fingerabdruck der IP-Adresse höchstens einen Tag, um das Raten zu bremsen. Schreibvorgänge zählen wir für die Tageslimits zwei Tage lang, ohne ihren Inhalt. Mit deinem Konto wird alles gelöscht; widerrufene Schlüssel löschen wir 12 Monate nach dem Widerruf. Einzelheiten stehen in Abschnitt 5.7 unserer Datenschutzerklärung.