Botanica/docs/API_EXAMPLES.md

Botanica API examples

All URLs below are relative to http://localhost:8155/api/v1 (or the configured HTTPS public origin). Health remains GET /health. Catalog, phenotype resolution and SVG preview are stateless public operations. Player-owned routes require the HttpOnly session cookie; writes additionally require an approved Origin and X-CSRF-Token returned by authentication or GET /me.

Session and recovery

• POST /auth/register and POST /auth/login: { "username": "your_name", "password": "your private password" }. Usernames are case-insensitive, 3–24 ASCII letters/digits/underscores; passwords are 10–128 characters.
• Signup returns five recoveryCodes once. Save them privately. POST /auth/recover takes username, new password and recoveryCode; a code works once and revokes prior sessions.
• GET /me: current identity, coins, XP, level and CSRF token. POST /auth/logout revokes the current session. Never put passwords, cookies or recovery codes in logs or URLs.

Game operations

GET /game/state returns the authoritative aggregate: player HUD, seed inventory, greenhouses with slots/timestamps, quests, shop/research unlocks, workers and the most recent offline calculation. Server UTC timestamps govern growth. Relevant reads/mutations reconcile bounded work under the player's row lock.

POST /game/action uses this envelope; generate a UUID once per intended operation and reuse it after a network failure:

{
  "action": "plant",
  "requestId": "a newly generated UUID",
  "data": { "slotId": "your owned empty slot UUID", "seedType": "starter" }
}

Operation data:

action	data
plant	slotId, seedType: starter/uncommon/rare
harvest	slotId
purchase	itemId from state.shop, optional owned houseId
sell	plantId
flags	plantId, favorite: boolean, protected: boolean
claim	questId from state.quests
research	researchId from state.research
hire	kind: gardener/breeder
assign	workerId, greenhouseId, enabled, policy

Policy fields: mode (repeat_crop/repeat_cross/target_trait), seedType, autoSell (false by default), reserveCoins (default 100), optional parentAId/parentBId, targetPigment and targetPattern. Breeders require two owned unsold game-grown parents. Target mode requires Selective breeding research and protects matching results without changing their odds. Saving a recipe starts it from the save time; no retroactive use of the new recipe.

The server validates prices, inventory, level, ownership and readiness. Reusing a request ID for different content returns 409. Receipt retries replay the stored result. Pending large offline backlogs return OFFLINE_PENDING; fetch state to process subsequent batches before spending newly obtained resources. Sales preserve ancestry rows and exclude sold specimens from inventory. Protected/favorite plants cannot be sold; automated sales additionally exclude first discoveries, non-Common plants and the last specimen of a species.

Collection and genetics

• GET /plants?limit=24&sort=newest: own unsold plants; optional q, species, pigment, pattern, rarity and cursor. Sorts: newest/oldest/name/rarity. Cursor is bound to its filter/sort; reset it after changing either.
• GET /plants/:id, /plants/:id/birth, /collection/stats, GET /breeding: owned detail, ancestry/event and collection/journal data. Sold records remain readable to their owner for lineage.
• POST /breeding: { "parentAId": "owned grown UUID", "parentBId": "another owned grown UUID", "idempotencyKey": "new UUID" }. Costs 75 coins at level 3. Authoritative genetics creates and records the child once, retaining both parents.
• POST /plants: advanced study only. Accepts speciesId, valid genome, name and optional cosmetic visualSeed. Excludes game rewards; no client-supplied rarity, mutations or ownership claims. This existing creative save operation is outside the monetary receipt API.
• GET /demo/plants?limit=100 and /demo/plants/:id: authenticated read-only reference herbarium. It never becomes player inventory.
• POST /phenotype/resolve: speciesId, paired-allele genome and optional preview mutations/catalogVersion. POST /preview additionally accepts visualSeed, growthStage (seedling/juvenile/mature/flowering), rendererVersion and background (warm/transparent). Outputs deterministic original SVG; no persisted game plant is created.

Errors use { "error": { "code": "...", "message": "..." } }; 401 means sign in, 403 means origin/CSRF rejection, 404 conceals inaccessible records, 409 indicates a game constraint and 429 throttles auth attempts. No client-provided owner ID is authoritative.