Skip to content

API & AI agents

Create an API key in Settings

Let your own tools — or an AI agent such as Claude, Cursor or Gemini — read public Fruit Pin pins and manage your own pins and photos. The API follows the same rules as the app: photos go through the same removal of location and camera data, contributions through the same checks, Privacy Mode and moderation.

REST API https://fruitpin.com/api/v1 · OpenAPI 3.1
MCP server https://fruitpin.com/mcp (Streamable HTTP)
Authentication Authorization: Bearer fp_live_…
Who every Fruit Pin account; writing needs a confirmed username
Rate limit 60 requests per minute per key, 120 per account (REST and MCP together)

What Fruit Pin is — and what it is not

Fruit Pin shows places. It offers no identification help and no advice on consumption. Many plants have look-alikes; only you can identify a plant with certainty, and you are responsible for what you collect. Your AI agent receives these rules every time it connects and is asked to point them out — check its answers anyway.

The API returns pins of other users without photo addresses: with location, species, access type and a link to the pin's page on Fruit Pin (web_url), where the photos can be seen. Your own photos come with their address. Do not combine pins of the same person into a profile (Terms of Use 6.9).

1. Create an API key

In the app, open Profile → Settings → API & AI agents, give the key a name (for example the agent that will use it) and choose its permissions:

Permission Allows
Read search public pins, read species, list your own pins and photos
Write create pins with a photo, add photos, correct positions, delete your pins and photos, hide or show your profile name

The key is shown once. We store only a fingerprint (SHA-256) of it and cannot show it again; if it is lost, revoke it and create a new one. Revoking takes effect on the next request. An account can have 10 active keys. To create a key we ask for your password if you signed in more than ten minutes ago. Changing your password revokes all keys.

Write needs a confirmed username. Photos through the API also need the Fruit Pin photo rules, confirmed once in the app (when you add a pin there, or with the checkbox next to the key).

Treat a key like a password: it acts in your name. Keep it out of code repositories and chat transcripts.

2. Connect your AI agent (MCP)

The MCP server gives an AI agent tools such as search_spots, get_spot, list_species, create_spot, add_photo, move_my_spot, delete_my_photo and delete_my_spot. The agent only sees the tools its key may use.

Claude Code

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

Cursor, VS Code and other clients with a JSON configuration

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

Claude Desktop (through the mcp-remote bridge)

{ "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_…" } } } }

Then ask, for example: "Which pins with walnut trees are within 2 km of Bonn main station?" or "Create a pin for the mirabelle tree in this photo at 50.7341, 7.0982 — ask me before you confirm the photo rules."

Clients that only connect through an OAuth flow without a custom header cannot connect yet.

3. Quick start with curl

Search public pins within 1 km:

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

Create a pin with its photo (the photo is required; no_persons_confirmed must be true):

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

Use /api/v1/species for the species ids. Send the same Idempotency-Key again after a timeout: you get the first answer back instead of a second pin.

4. Rules for contributions

  • Photos: JPEG, at most 8 MB. Location and camera data are removed before the photo becomes public; a photo where that fails is rejected and not stored.
  • Photo rules: each photo needs no_persons_confirmed: true — no identifiable people, no licence plates, no house numbers or doorbell labels. An agent must ask you before it confirms this.
  • Species: only species from /api/v1/species. Mushrooms are not part of Fruit Pin. For species with a confusion note, species_note_confirmed: true says that you read the note and identified the species yourself with certainty.
  • Duplicates: if a pin of the same species exists within 50 m, you get 409 possible_duplicate with its id. Add your photo there, or create a separate pin with allow_nearby: true.
  • Privacy Mode (on by default): new pins and photos become visible to others at the next 6:00 (Berlin time) at least 24 hours after the upload.
  • Positions are public. Do not set pins at your own home address. Choose access_type honestly: oeffentlich (public land), freigegeben (the owner allows access) or unklar (unclear).
  • Collecting: only small amounts for personal use, carefully and only where entering is allowed.
  • Changing and deleting: a pin can be moved at most 50 m from where it was created. Pins and photos cannot be changed or deleted while they are being reviewed; a pin with photos from other people cannot be deleted, and the only photo of your pin can only go together with the pin.

5. Limits and errors

Limit Value
Requests 60 per minute per key, 120 per minute per account
New pins 20 per 24 hours
Photos 40 per 24 hours
Changes (position, profile name) 60 per 24 hours
Deletions 30 per 24 hours
Search area radius up to 10 km, or a box up to 0.5° per side
Page size up to 100, paginate with next_cursor

Errors are JSON: { "error": "daily_limit_exceeded", "message": "…" }. A 429 carries Retry-After. Content of other accounts is answered with 404 — the API does not reveal whether it exists.

6. What we store

Of a key: its name, the first 14 characters, a fingerprint (SHA-256), its permissions and when it was created, last used and revoked. After a failed sign-in we keep a fingerprint of the IP address for at most one day to slow down guessing. Write actions are counted for the daily limits for two days, without their content. Everything is deleted with your account; revoked keys are deleted 12 months after revocation. Details are in section 5.7 of our privacy policy.