Treegens API

This is the backend for the Treegens Game (GROWalition): a cross-player leaderboard and counter, a cloud-save service for player progress, and a small read-only proxy onto public Treegens platform stats. It is a purpose-built API for that game client, published here for transparency rather than as a general third-party platform: there is no signup flow or issued API key.

Authentication

Two of the three endpoint groups need no credential at all; the third uses a bearer secret that is shown to the caller exactly once. There is no OAuth flow, no API key issuance, and no account system.

Health & status

Not published: there is no dedicated /health or status endpoint, and no uptime/SLA figure is published for this API. Do not treat any number on this page as an uptime guarantee.

Quick start

The fastest way to see a real response is the public leaderboard endpoint. It needs no credential and no request body:

curl https://treegens-api.netlify.app/api/grow

Not run yet. This calls the real, public /api/grow endpoint relative to this page. Nothing is faked. It does not call /api/tg: browser GET from this origin is rejected.

Example response shape

This mirrors the fields /api/grow actually returns on GET. Numbers below are illustrative placeholders, not a live snapshot. Use "Try it live" above for real current values.

{
  "you": null,
  "weekly": { "week": 3021, "goal": 5000, "planted": 812 },
  "counter": 48210,
  "growers": 137,
  "realTrees": 0,
  "board": [
    { "name": "Treegen", "exp": 9120, "trees": 340, "real": 0, "id": "a1b2c3" }
  ],
  "daily": {
    "day": 20323,
    "players": 22,
    "top": [ { "name": "Treegen", "score": 14200, "id": "a1b2c3" } ]
  }
}

Pass ?id=<yourPlayerId> on the request to also receive a you object with your leaderboard rank; player ids in board and daily.top are always truncated to 6 characters for privacy.

Endpoints

Save, resume, return

Cloud save is how a player comes back. Create a save once, keep the recovery secret on the device, then GET to resume. This API never re-shows a lost secret.

Create (secret shown once)

exp and grove are required. The 201 body includes id, recoverySecret (this once only), expiresAt, session, version, and savedAt. Copy recoverySecret off the response immediately.

curl -sS -X POST https://treegens-api.netlify.app/api/save \
  -H "content-type: application/json" \
  -d '{"action":"create","save":{"exp":0,"grove":[]}}'

Resume

Replace the placeholders with values from the create response. Do not put the secret in the query string: that is rejected as 400 credential-in-url.

curl -sS "https://treegens-api.netlify.app/api/save?id=YOUR_SAVE_ID" \
  -H "Authorization: Bearer YOUR_RECOVERY_SECRET"

The 200 body is { id, version, savedAt, save }. Autosave for 30 minutes: POST action: "session", then send X-Grow-Session instead of the secret. To write progress after resume, POST action: "save" with the version you just read as baseVersion. A mismatch returns 409 conflict with the server version, so re-GET and retry.

Rate limits

Limits are enforced server-side per caller (fixed one-hour windows) with an additional shared cap across all callers. There is no Retry-After header on a 429 today, so back off and retry after roughly the window shown.

action: "claim-legacy" is disabled by default and returns 403 migration-unavailable unless an operator explicitly turns it on; it exists only to migrate pre-v2 saves.

Security notes

Support

This API doesn't have a dedicated status page or ticketing system. For questions, integration issues, or to report a problem, email jimi@wemakeimpact.org (the same contact used for Treegens Game support).