# Shared Forest: full agent guide

> Shared Forest is a free, shared illustrated forest that grows from its traffic. Every page load adds growth energy, and every visitor, human or AI agent, can plant one tree per day.

## How the forest grows

1. Every page load sends `POST /api/visit` with `{"plant": false}`. It adds anonymous growth energy that grows existing trees. The server stores no identifier for it. A global rate cap stops floods from exploding the forest.
2. A visitor who clicks "Plant your tree" sends `{"plant": true}`. The server plants one tree per visitor per day. It deduplicates with SHA-256(daily salt + IP + User-Agent) and never stores the raw IP.
3. The server classifies each visit as `human`, `agent` or `bot`. Trees planted by AI agents carry `origin: "agent"`.
4. Trees grow through stages 0-5 (grass patch, sprout, sapling, young tree, mature tree, ancient tree). Dense trees merge into groves that level up.
5. The live canvas receives every change over a WebSocket within seconds.

## Plant a tree as an agent

- MCP: call `plant_tree` on the MCP server at https://sharedforest.com/mcp. Optional argument: `idempotency_key`.
- HTTP: send `POST /api/visit` with the body `{"plant":true}`. Add an `Idempotency-Key` header to make retries safe.
- Response: `{"queued": true, "visitId": "<uuid>", "plant": true}`. The tree appears within seconds. A second plant on the same day grows the forest but plants no new tree.

```sh
curl -X POST https://sharedforest.com/api/visit -H 'Content-Type: application/json' -H "Idempotency-Key: $(uuidgen)" -d '{"plant":true}'
```

## Read the forest

- `GET /api/forest` returns `{trees, groves, stats, visitors, uniqueVisitors, generatedAt}`.
- Add `limit` (1-500), `cursor` or `bbox` (minX,minY,maxX,maxY) to page through trees. The response then adds `nextCursor`, `limit` and `totalTrees`.
- `stats` holds `{humans, agents, bots, plantedToday}`. Totals count since launch, except `plantedToday`.

## MCP tools

| Tool | Effect |
|---|---|
| get_forest_stats | Read-only. Counts of trees, groves, visitors and traffic classes. |
| get_forest | Read-only. Bounded summary: counts per tree type and stage, grove levels, newest trees. |
| list_trees | Read-only. One page of trees with cursor pagination and an optional bounding box, the same as GET /api/forest?limit=. |
| plant_tree | Writes. Plants one tree for the caller (one per day). Returns a visitId. |
| explain_shared_forest | Read-only. This guide as Markdown. |
| get_price_quote | Read-only. Price of N sponsored trees (cents, VAT included). |
| design_tree | Writes. Designs a custom tree from a wish. Returns design_id. 3 per day. |
| get_design | Read-only. One design by design_id. |
| find_spots | Read-only. Free positions for N sponsored trees, optionally near a point. |
| start_sponsorship | Writes. OAuth scope sponsor:write. Creates an unpaid order for the signed-in user, within the spending limit. Returns confirm_url for the user and next_step. Charges nothing. |
| get_order | Read-only. OAuth scope account:read or sponsor:write. Status and tree ids of one of the user's orders. |
| my_orders | Read-only. OAuth scope account:read. The user's orders. |
| my_trees | Read-only. OAuth scope account:read. The user's sponsored trees with links. |

The docs MCP server at https://sharedforest.com/mcp/docs has search_docs and read_doc.

## Sponsor trees via API or MCP

A sponsorship puts 1-100 custom-designed trees in the forest for 12 months. Each tree shows a display name (1-32 characters) and an optional https link, labelled "Sponsored". The name goes live after automatic checks. The link goes live after a manual review. Prices include VAT. See [pricing](https://sharedforest.com/pricing.md).

| Trees per order | Unit price | Renewal per tree | Discount | Example |
|---|---|---|---|---|
| 1-4 | 9.00 EUR | 4.50 EUR | 0 % | 1 tree = 9.00 EUR |
| 5-9 | 7.80 EUR | 3.90 EUR | 13 % | 5 trees = 39.00 EUR |
| 10-24 | 6.90 EUR | 3.45 EUR | 23 % | 10 trees = 69.00 EUR |
| 25-99 | 5.96 EUR | 2.98 EUR | 34 % | 25 trees = 149.00 EUR |
| 100 | 4.90 EUR | 2.45 EUR | 46 % | 100 trees = 490.00 EUR |

Steps:

1. Quote: MCP `get_price_quote` or `GET /api/v1/pricing/quote?quantity=5`.
2. Design: MCP `design_tree` with a wish (1-200 characters) or `POST /api/v1/designs` `{"wish": "..."}`. Returns a `design_id` (`dsn_...`). Max 3 designs per caller per day. One design for all trees, or one per tree.
3. Place (optional): MCP `find_spots` or `GET /api/v1/spots?quantity=5&near=4096,4096`. REST callers hold spots with `POST /api/v1/holds` and free unused ones with `DELETE /api/v1/holds/{id}`. Omit spots and the server picks free ones.
4. Order: MCP `start_sponsorship` (needs an OAuth token with scope `sponsor:write`; the order belongs to the user's account and must fit the spending limit set at consent) or `POST /api/v1/orders` with `channel: "mcp"` or `"api"` and an `Idempotency-Key`. The order is unpaid. It expires 30 minutes after creation unless the human confirms. `POST /api/v1/orders/{id}/extend` adds 30 minutes once; the confirm page does this when it opens. The response has `confirmUrl` (https://sharedforest.com/sponsor/confirm/ord_...).
5. Hand over: give `confirmUrl` to your user. The user accepts the terms, gives the withdrawal consent and pays on Stripe. That page calls `POST /api/v1/orders/{id}/confirm`.
6. Follow up: MCP `get_order` or `GET /api/v1/orders/{id}` every 10 seconds or more until `status` is `fulfilled`. `refund_pending` means paid but not plantable: the operator refunds. `treeIds` then lists the new trees. Share https://sharedforest.com/?tree=<id>.

```sh
curl -s "https://sharedforest.com/api/v1/pricing/quote?quantity=5"
curl -s -X POST https://sharedforest.com/api/v1/designs -H 'Content-Type: application/json' -d '{"wish":"a silver birch with warm lanterns"}'
curl -s -X POST https://sharedforest.com/api/v1/orders -H 'Content-Type: application/json' -H "Idempotency-Key: $(uuidgen)" \
  -d '{"quantity":5,"designIds":["dsn_abc123"],"displayName":"Ada","email":"ada@example.com","channel":"api"}'
```

What an agent can do: quote, design, select spots, create an unpaid order, read its status.
What an agent cannot do: accept the terms, give the withdrawal consent or pay for a consumer. German consumer law requires the consumer's own click on "Order and pay" (§ 312j (3) BGB) and the consumer's own express consent before the display starts (§ 356 (5) BGB). So a human always confirms on `confirmUrl`.

Business buyers (phase 2, off until announced): `POST /api/v1/orders/{id}/pay` with the buyer's EU VAT id answers `402` with a Machine Payments Protocol challenge (`WWW-Authenticate: Payment`). Retry with a Stripe Shared Payment Token. This path is B2B only because the consumer rules above do not apply to businesses. It appears in the OpenAPI document only when it is on.

Errors are problem+json: `422` blocked name, link or wish; `409` spot taken or sold out; `429` rate limit or cap (3 designs per caller per day, 100 held spots per IP, 3 open orders per email, 300 unconfirmed spots in total); `502` payment provider down; `503` sales not open yet.

## Limits

- API, MCP and /ask requests: 120 per minute per IP address. Every response carries `RateLimit` and `RateLimit-Policy` headers. A 429 carries `Retry-After`.
- MCP request bodies over 16 KiB return 413.
- `/api/forest` is cached for 30 seconds.
- Authentication: none for reading, planting and the docs server. Account tools need an OAuth 2.1 access token (PKCE S256, 15-minute tokens, rotating refresh tokens). Walkthrough: https://sharedforest.com/auth.md.

## Errors

Every API error is `application/problem+json` (RFC 9457) with `type`, `title`, `status` and `detail`. The `detail` field tells you how to fix the request.

## Versioning

The REST API is version 1. Every API response carries the header `API-Version: 1`. The paths /api/v1/forest and /api/v1/visit are stable aliases. Changes inside a version are additive only. A breaking change gets a new path version. The old path then returns `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers for at least 90 days before removal. The OpenAPI document states this policy in `x-versioning-policy`.

## Discovery files

- https://sharedforest.com/llms.txt
- https://sharedforest.com/openapi.json
- https://sharedforest.com/.well-known/api-catalog
- https://sharedforest.com/.well-known/mcp/server-card.json (product MCP server)
- https://sharedforest.com/mcp/docs/.well-known/mcp/server-card.json (docs MCP server)
- https://sharedforest.com/.well-known/agent-card.json
- https://sharedforest.com/.well-known/ai-catalog.json
- https://sharedforest.com/.well-known/agent-skills/index.json
- https://sharedforest.com/sitemap.xml
- https://github.com/ArneFfm/shared-forest-agents (AGENTS.md, plugin.json, mcp.json, server.json, skills)

## Operator

Arne Kellmann, Ober-Ramstadt, Germany. Contact: contact@ghardenlab.com. Legal notice: https://sharedforest.com/impressum.