Gardener's Almanac

Vouch for another gardener's community-submitted plant, as a signal of trust to others browsing the catalogue. A gardener cannot endorse their own submission.

endorse_plant

Return a garden the authenticated gardener can see — owned or shared with them — by id, with the same enrichment as list_gardens. Each garden with coordinates carries climate_support: state "seasonal" or "aseasonal", and provisional true while it is a guess from latitude alone because the location's climate data is still being fetched. Aseasonal means we decline to compute a growing calendar there at all — no sowing or harvest timings, no generated sow/harvest to-dos — while the event log, plantings, sharing and watering guidance work normally. Do not repeat a provisional verdict as settled: it is often overturned within the minute, and most tropical locations turn out to be seasonal.

get_garden

Return one plant's full catalogue entry (growing/care/harvesting/kitchen instructions). Pass garden_id to also get localised sowing/planting/harvest timing hints for that garden's location. If hints_pending comes back true the timings are still being computed for that location; say so rather than reporting the plant as having no timings. Hints absent *without* hints_pending mean this garden's location has no thermal season (equatorial and other thermally flat places), where no temperature-derived calendar carries information and none is computed; the planting says so itself with hints_unavailable_reason: "no_thermal_season". Say that, rather than that the plant has no timings. Everything else about the garden works normally there, watering guidance included.

get_plant

Return one knowledge-base article's full content by slug (as returned by list_articles).

get_article

Return the authenticated gardener's own account record (email, locale, consent status). Takes no input.

get_me

Return one planting's full event history, current tasks, growth stage, and personal calendar (predicted upcoming dates based on this gardener's own logged events).

get_planting_activity

Return the current dryness score, watering recommendation, and 7-day forecast for one of the authenticated gardener's own gardens. Returns a null notification when the garden has no location set or too little data yet. Pass area_id to ask about one growing place instead; without it, a garden that has growing areas already answers for its driest one and names it.

get_watering_forecast

List the named growing places inside a garden — a greenhouse, a raised bed, pots on a patio — with each one's current dryness. A garden may have none, which is the default and means the whole garden is treated as one place.

list_areas

List the knowledge-base article summaries (title, slug, summary, category) available in a language. Defaults to the authenticated gardener's own locale. Articles arrive grouped by category — all of one, then all of the next, newest first within each — so a summary can follow that order rather than inventing one.

list_articles

List the logged events (watering, soil checks, sowing, planting, harvest, notes, weeding, ...) for one of the authenticated gardener's own gardens — the permanent garden logbook. Optionally filter by event type and/or a since timestamp.

list_events

List every garden the authenticated gardener can see — the ones they own plus any shared with them — with each garden's role (owner, writer or reader), the name of its owner when it isn't theirs, active plant count, last-watered/last-soil-check timestamps, and a one-line status caption (e.g. needs watering). owner_label is a display name, not a contactable address. Takes no input. Each garden with coordinates carries climate_support: state "seasonal" or "aseasonal", and provisional true while it is a guess from latitude alone because the location's climate data is still being fetched. Aseasonal means we decline to compute a growing calendar there at all — no sowing or harvest timings, no generated sow/harvest to-dos — while the event log, plantings, sharing and watering guidance work normally. Do not repeat a provisional verdict as settled: it is often overturned within the minute, and most tropical locations turn out to be seasonal.

list_gardens

List the plantings in one of the authenticated gardener's own gardens (what's currently growing, or the archived/removed history). Includes localised sowing/planting/harvest timing hints for active plantings when the garden has a location set. A planting with hints_pending true has timings that are still being computed for this garden's location — absent hint fields there mean 'not ready yet', not 'this plant has none'. Hints absent *without* hints_pending mean this garden's location has no thermal season (equatorial and other thermally flat places), where no temperature-derived calendar carries information and none is computed; the planting says so itself with hints_unavailable_reason: "no_thermal_season". Say that, rather than that the plant has no timings. Everything else about the garden works normally there, watering guidance included.

list_plantings

List the pending and dismissed tasks (to-dos) for one of the authenticated gardener's own gardens, plus a virtual watering entry point that's always present. Completed (done) tasks are excluded.

list_tasks

List the crops that have been grown in one growing area, most recently logged first — read from the sowings, plantings out and harvests recorded there. A planting itself carries no area, so this is the only record of where a crop went. An annual is listed within the current growing season; a perennial stays wherever its last lifecycle event put it, however long ago, because it is not re-sown.

list_area_plantings

Return the gardeners who can see a garden — its owner and anyone it has been shared with, each with their role. People are named by a short display label, never a contactable email address. Someone who has been invited but has not accepted yet is not listed, because they cannot see the garden yet. Inviting and removing people is done in the app, not here.

list_garden_members

Log a watering, soil-moisture check, weeding, soil preparation, or free-form note against one of the authenticated gardener's own gardens — the permanent garden logbook. Soil preparation is work done to the ground itself (a cover laid, a bed opened up, compost spread); name the bed with area_id rather than a planting. Plant lifecycle steps (sowing, planting out, harvesting) are not logged here — use log_plant_lifecycle instead.

log_event

Log a plant lifecycle step (sow, sow indoors, plant out, or harvest) for one of the authenticated gardener's own plantings, without reference to a specific to-do card — use this for backfilling or repeat logging (e.g. a second harvest picking). May spawn a follow-up to-do (e.g. sowing spawns an expected-harvest reminder).

log_plant_lifecycle

Remove a planting from one of the authenticated gardener's own gardens. This archives it (and its event history) rather than deleting it outright — see restore_planting.

remove_planting

Withdraw the authenticated gardener's own previous endorsement of a community-submitted plant.

remove_endorsement

Change the due date of one of the authenticated gardener's own pending to-dos. Only pending tasks can be rescheduled.

reschedule_task

Return one of the authenticated gardener's own dismissed to-dos to pending, so it can notify and be logged again.

restore_task

Bring back a planting that was previously removed from one of the authenticated gardener's own gardens, and regenerate its current to-dos. Returns the restored planting with its timing hints; hints_pending true means they are still being computed, not absent. Hints absent *without* hints_pending mean this garden's location has no thermal season (equatorial and other thermally flat places), where no temperature-derived calendar carries information and none is computed; the planting says so itself with hints_unavailable_reason: "no_thermal_season". Say that, rather than that the plant has no timings. Everything else about the garden works normally there, watering guidance included.

restore_planting

Search the shared plant catalogue by free-text query and/or labels. Returns a paginated result; also includes the authenticated gardener's own submitted plants. Search is typo-tolerant and spans every locale's names plus recorded alternates, so "Rutabaga", "Kålrot" and "Swede" all find the same plant. Pass garden_id to rank results by how well each suits that garden and to get a fit verdict per plant: fit is "good", "tight" or "poor" with fit_reason naming what is wrong (season_too_short, needs_more_sun, not_for_growing_environment). Ranking never excludes — a poor match sinks rather than disappearing — and an absent fit means the question could not be answered for that garden, not that the plant is fine.

search_plants

Add a new plant to the shared catalogue for other gardeners to find and grow — only its common name is required; growing details (temperature thresholds, spacing, days to maturity, etc.) can be filled in now or left for later. Numbers are checked for plausibility and a minimum must not exceed its maximum. The same gardener cannot submit two plants by the same name; somebody else having submitted it is fine and is what `endorse_plant` is for.

submit_plant

Update one of the authenticated gardener's own gardens: name, location, and microclimate settings (sun exposure, rain exposure, soil type, growing environment). All fields are replaced with the given values, matching PUT semantics — omitted microclimate fields reset to none set. Each garden with coordinates carries climate_support: state "seasonal" or "aseasonal", and provisional true while it is a guess from latitude alone because the location's climate data is still being fetched. Aseasonal means we decline to compute a growing calendar there at all — no sowing or harvest timings, no generated sow/harvest to-dos — while the event log, plantings, sharing and watering guidance work normally. Do not repeat a provisional verdict as settled: it is often overturned within the minute, and most tropical locations turn out to be seasonal.

update_garden

Rename a growing area or change its conditions. Omitted fields are left exactly as they are — this is a partial update, not a replacement. To make a condition follow the garden again, set the matching inherit_* flag rather than guessing at a value. Send one or the other for a given condition, never both.

update_area

Correct a previously logged event's timestamp, note, and (for watering or soil-moisture checks) level — full replace, matching PATCH semantics: an omitted note clears it, an omitted level keeps the event's existing one. Only plant-lifecycle and garden-level user events can be edited this way; system-generated events cannot.

update_event

Update growing-threshold fields on one of the authenticated gardener's own catalogue submissions (temperature thresholds, spacing, days to maturity, etc.). This is a merge: an omitted field is left as it is. To erase a field, name it in `clear` — and don't also give it a value in the same call, which is rejected. Cannot rename an existing submission's common_name; resubmit via submit_plant for that.

update_submission