Overview

Gardens are the top-level organizational unit in Garden.gg. Each user can have multiple gardens, and each garden contains plots where plants grow. Gardens can be made public for the community to browse.

Endpoints

List Gardens

Retrieve a paginated list of your gardens.

GET /gardens

Query Parameters

Response 200 OK

{
  "data": [
    {
      "id": "gdn_a1b2c3d4",
      "name": "Backyard Paradise",
      "location": "Portland, OR",
      "zone": "8b",
      "is_public": true,
      "plot_count": 4,
      "created_at": "2026-01-15T08:30:00Z",
      "updated_at": "2026-03-10T14:20:00Z"
    },
    {
      "id": "gdn_e5f6g7h8",
      "name": "Community Plot",
      "location": "SE Division St",
      "zone": "8b",
      "is_public": false,
      "plot_count": 1,
      "created_at": "2026-02-20T12:00:00Z",
      "updated_at": "2026-02-20T12:00:00Z"
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 20
}

Examples

cURL

curl -X GET "https://garden.gg/api/v1/gardens" \
  -H "Authorization: Bearer gg_live_your_api_key_here"

Python

import requests

headers = {"Authorization": "Bearer gg_live_your_api_key_here"}
response = requests.get("https://garden.gg/api/v1/gardens", headers=headers)
gardens = response.json()

for garden in gardens["data"]:
    print(f"{garden['name']} — {garden['plot_count']} plots")

Node.js

const response = await fetch("https://garden.gg/api/v1/gardens", {
  headers: { Authorization: "Bearer gg_live_your_api_key_here" },
});

const { data: gardens } = await response.json();
gardens.forEach((g) => console.log(`${g.name} — ${g.plot_count} plots`));

Create Garden

Create a new garden.

POST /gardens

Request Body

Request

{
  "name": "Rooftop Herbs",
  "location": "Brooklyn, NY",
  "zone": "7a",
  "is_public": true
}

Response 201 Created

{
  "id": "gdn_i9j0k1l2",
  "name": "Rooftop Herbs",
  "location": "Brooklyn, NY",
  "zone": "7a",
  "is_public": true,
  "plot_count": 0,
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z"
}

Examples

cURL

curl -X POST "https://garden.gg/api/v1/gardens" \
  -H "Authorization: Bearer gg_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rooftop Herbs",
    "location": "Brooklyn, NY",
    "zone": "7a",
    "is_public": true
  }'

Python

import requests

headers = {
    "Authorization": "Bearer gg_live_your_api_key_here",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://garden.gg/api/v1/gardens",
    headers=headers,
    json={
        "name": "Rooftop Herbs",
        "location": "Brooklyn, NY",
        "zone": "7a",
        "is_public": True,
    },
)

garden = response.json()
print(f"Created garden: {garden['id']}")

Node.js

const response = await fetch("https://garden.gg/api/v1/gardens", {
  method: "POST",
  headers: {
    Authorization: "Bearer gg_live_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Rooftop Herbs",
    location: "Brooklyn, NY",
    zone: "7a",
    is_public: true,
  }),
});

const garden = await response.json();
console.log(`Created garden: ${garden.id}`);

Get Garden

Retrieve a single garden by ID.

GET /gardens/:id

Response 200 OK

{
  "id": "gdn_a1b2c3d4",
  "name": "Backyard Paradise",
  "location": "Portland, OR",
  "zone": "8b",
  "is_public": true,
  "plot_count": 4,
  "plots": [
    {
      "id": "plt_m3n4o5p6",
      "name": "Tomato Beds",
      "plot_type": "raised_bed",
      "plant_count": 6
    }
  ],
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-10T14:20:00Z"
}

Update Garden

Update an existing garden. Only include the fields you want to change.

PUT /gardens/:id

Request Body

Request

{
  "name": "Backyard Paradise 2.0",
  "is_public": false
}

Response 200 OK

Returns the full updated garden object.

Delete Garden

Delete a garden and all its plots, plants, and events. This action is irreversible.

DELETE /gardens/:id

Response 204 No Content

No response body.

Browse Public Gardens

Browse gardens that have been made public by their owners. This endpoint does not require authentication.

GET /gardens/public

Query Parameters

Response 200 OK

{
  "data": [
    {
      "id": "gdn_a1b2c3d4",
      "name": "Backyard Paradise",
      "location": "Portland, OR",
      "zone": "8b",
      "plot_count": 4,
      "owner": {
        "username": "green_thumb",
        "display_name": "Green Thumb",
        "level": 12
      }
    }
  ],
  "total": 156,
  "page": 1,
  "per_page": 20
}

Error Responses