Kendi programlarının — ya da Claude, Cursor veya Gemini gibi bir yapay zekâ ajanının — Fruit Pin’deki herkese açık iğneleri okumasını ve kendi iğnelerini ve fotoğraflarını yönetmesini sağla. API, uygulamayla aynı kurallara uyar: Fotoğraflardan konum ve kamera verileri aynı şekilde silinir; katkılar aynı denetimlerden, Privacy Mode’dan ve moderasyondan geçer.
| REST API | https://fruitpin.com/api/v1 · OpenAPI 3.1 |
| MCP sunucusu | https://fruitpin.com/mcp (Streamable HTTP) |
| Kimlik doğrulama | Authorization: Bearer fp_live_… |
| Kimler için | her Fruit Pin hesabı; yazmak için onaylı bir kullanıcı adı gerekir |
| İstek sınırı | anahtar başına dakikada 60, hesap başına 120 istek (REST ve MCP birlikte) |
Fruit Pin nedir — ve ne değildir
Fruit Pin yerleri gösterir. Tür tanıma yardımı sunmaz ve tüketim önerisi vermez. Pek çok bitkinin benzeri vardır; bir bitkiyi kesin olarak yalnızca sen tanıyabilirsin ve topladıklarının sorumluluğu sana aittir. Yapay zekâ ajanın her bağlantıda bu kuralları alır ve seni bunlar hakkında uyarması istenir — yine de yanıtlarını kontrol et.
API, diğer kullanıcıların iğnelerini fotoğraf adresleri olmadan verir: konum, tür, erişim türü ve fotoğrafların görülebildiği Fruit Pin’deki iğne sayfasına bir bağlantı (web_url) ile. Kendi fotoğraflarını adresleriyle alırsın. Aynı kişinin iğnelerini bir profilde birleştirme (Kullanım Koşulları 6.9).
1. API anahtarı oluştur
Uygulamada Profil → Ayarlar → API ve yapay zekâ ajanları bölümünü aç, anahtara bir ad ver (örneğin onu kullanacak ajanın adı) ve izinleri seç:
| İzin | İzin verilenler |
|---|---|
| Okuma | herkese açık iğneleri aramak, türleri okumak, kendi iğnelerini ve fotoğraflarını listelemek |
| Yazma | fotoğraflı iğne eklemek, fotoğraf eklemek, konumları düzeltmek, kendi iğnelerini ve fotoğraflarını silmek, profil adını gizlemek veya göstermek |
Anahtar bir kez gösterilir. Yalnızca bir parmak izini (SHA-256) saklarız ve onu tekrar gösteremeyiz; kaybolursa iptal et ve yenisini oluştur. İptal bir sonraki istekten itibaren geçerlidir. Bir hesabın en fazla 10 etkin anahtarı olabilir. Anahtar oluşturmak için, on dakikadan uzun süre önce giriş yaptıysan parolanı sorarız. Parolanı değiştirirsen tüm anahtarlar iptal edilir.
Yazma için onaylı bir kullanıcı adı gerekir. API üzerinden fotoğraflar için ayrıca Fruit Pin fotoğraf kurallarının uygulamada bir kez onaylanmış olması gerekir (orada bir iğne eklerken veya anahtarın yanındaki onay kutusuyla).
Anahtarı bir parola gibi sakla: Senin adına işlem yapar. Kod depolarına ve sohbet geçmişlerine koyma.
2. Yapay zekâ ajanını bağla (MCP)
MCP sunucusu bir yapay zekâ ajanına search_spots, get_spot, list_species, create_spot, add_photo, move_my_spot, delete_my_photo ve delete_my_spot gibi araçlar sunar. Ajan yalnızca anahtarının kullanabileceği araçları görür.
Claude Code
claude mcp add --transport http fruitpin https://fruitpin.com/mcp \
--header "Authorization: Bearer fp_live_…"
Cursor, VS Code ve JSON ayarı olan diğer istemciler
{ "mcpServers": { "fruitpin": { "url": "https://fruitpin.com/mcp", "headers": { "Authorization": "Bearer fp_live_…" } } } }
Claude Desktop (mcp-remote köprüsüyle)
{ "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_…" } } } }
Sonra örneğin şunu sor: „Bonn ana tren istasyonunun 2 km çevresinde ceviz ağaçlı hangi iğneler var?" ya da „Bu fotoğraftaki mirabel ağacı için 50.7341, 7.0982 konumunda bir iğne oluştur — fotoğraf kurallarını onaylamadan önce bana sor."
Yalnızca özel başlık olmadan bir OAuth akışıyla bağlanan istemciler henüz bağlanamaz.
3. curl ile hızlı başlangıç
1 km çevresindeki herkese açık iğneleri ara:
curl "https://fruitpin.com/api/v1/spots?lat=50.7341&lng=7.0982&radius_m=1000" \
-H "Authorization: Bearer fp_live_…"
Fotoğrafıyla birlikte bir iğne oluştur (fotoğraf zorunludur; no_persons_confirmed true olmalıdır):
curl https://fruitpin.com/api/v1/me/spots \
-H "Authorization: Bearer fp_live_…" \
-H "Idempotency-Key: mirabelle-2026-11-01" \
-F photo=@agac.jpg \
-F 'metadata={"species_id":"sp-mirabelle","lat":50.7341,"lng":7.0982,"access_type":"oeffentlich","access_note":"Çayır yolunun kenarı","no_persons_confirmed":true}'
Tür kimliklerini /api/v1/species verir. Zaman aşımından sonra aynı Idempotency-Key ile tekrar gönder: İkinci bir iğne yerine ilk yanıtı geri alırsın.
4. Katkı kuralları
- Fotoğraflar: JPEG, en fazla 8 MB. Bir fotoğraf herkese açık olmadan önce konum ve kamera verileri silinir; bunun başarısız olduğu bir fotoğraf reddedilir ve saklanmaz.
- Fotoğraf kuralları: Her fotoğraf için
no_persons_confirmed: truegerekir — tanınabilir kişi, araç plakası, kapı numarası veya zil etiketi olmamalı. Bir ajan bunu onaylamadan önce sana sormalıdır. - Türler: yalnızca
/api/v1/specieslistesindeki türler. Mantarlar Fruit Pin’in parçası değildir. Karışıklık notu olan türlerdespecies_note_confirmed: true, notu okuduğunu ve türü kendin kesin olarak tanıdığını belirtir. - Yinelenenler: 50 m içinde aynı türden bir iğne varsa, kimliğiyle birlikte
409 possible_duplicategelir. Fotoğrafını oraya ekle ya daallow_nearby: trueile yine de ayrı bir iğne oluştur. - Privacy Mode (varsayılan olarak açık): Yeni iğneler ve fotoğraflar, yüklemeden en az 24 saat sonraki ilk sabah 6:00’da (Almanya saati) başkalarına görünür olur.
- Konumlar herkese açıktır. Kendi ev adresine iğne koyma.
access_typedeğerini dürüstçe seç:oeffentlich(kamuya ait alan),freigegeben(sahibi erişime izin veriyor) veyaunklar(belirsiz). - Toplama: yalnızca kişisel ihtiyaç için az miktarda, özenle ve yalnızca girmenin serbest olduğu yerlerde (Handstrauß kuralı).
- Değiştirme ve silme: Bir iğne, oluşturulduğu yerden en fazla 50 m taşınabilir. Moderasyon incelemesi sürerken iğneler ve fotoğraflar değiştirilemez ve silinemez; başkalarının fotoğraf eklediği bir iğne silinemez ve iğnenin tek fotoğrafı yalnızca iğneyle birlikte silinebilir.
5. Sınırlar ve hatalar
| Sınır | Değer |
|---|---|
| İstekler | anahtar başına dakikada 60, hesap başına dakikada 120 |
| Yeni iğneler | 24 saatte 20 |
| Fotoğraflar | 24 saatte 40 |
| Değişiklikler (konum, profil adı) | 24 saatte 60 |
| Silmeler | 24 saatte 30 |
| Arama alanı | 10 km’ye kadar yarıçap veya kenar başına en fazla 0,5° olan bir dikdörtgen |
| Sayfa boyutu | en fazla 100, next_cursor ile devam |
Hatalar JSON olarak gelir: { "error": "daily_limit_exceeded", "message": "…" }. Bir 429 yanıtı Retry-After içerir. Başka hesapların içeriklerine API 404 ile yanıt verir — var olup olmadıklarını açığa vurmaz.
6. Neleri saklıyoruz
Bir anahtardan: adını, ilk 14 karakterini, bir parmak izini (SHA-256), izinlerini ve ne zaman oluşturulduğunu, en son kullanıldığını ve iptal edildiğini. Başarısız bir girişten sonra tahmin denemelerini yavaşlatmak için IP adresinin bir parmak izini en fazla bir gün saklarız. Yazma işlemlerini günlük sınırlar için iki gün boyunca, içerikleri olmadan sayarız. Hesabınla birlikte her şey silinir; iptal edilen anahtarları iptalden 12 ay sonra sileriz. Ayrıntılar gizlilik politikamızın 5.7 bölümünde.