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: truesays 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_duplicatewith its id. Add your photo there, or create a separate pin withallow_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_typehonestly:oeffentlich(public land),freigegeben(the owner allows access) orunklar(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.