Open Plantbook

Schema-first Open Plantbook API workflows

Use this skill when the user asks about Open Plantbook, plant-care thresholds, plant lookup by scientific/common name, plant details, multilingual aliases, creating/updating/deleting Open Plantbook user plants, or authenticated Open Plantbook plant workflows.

Open Plantbook is a community-sourced plant-care database. Its API supports API-key token authentication and OAuth2 client credentials. This skill uses direct HTTP against the live API schema; it does not require or depend on an SDK.

The packaged helper sends authenticated requests only to the official Open Plantbook API host, https://open.plantbook.io. Do not configure alternate API hosts for real user credentials. If you need to test a fork, mock, or staging API, use separate throwaway credentials outside this published helper.

Schema-first rule

Before any Open Plantbook API operation where endpoint shape, payload fields, limits, or response shape matter, consult the live OpenAPI schema:

bash

curl -sS -H 'Accept: application/json' -A 'openplantbook-agent-skill/1.0 (+https://open.plantbook.io/docs/)' https://open.plantbook.io/api/schema/

Canonical schema endpoint:

• https://open.plantbook.io/api/schema/

Do not use /api/v1/schema/; it returns 404. The schema verified during this update advertises OpenAPI 3.0.3 and API version 202606.

Use the schema as the source of truth for paths, methods, security, parameters, request bodies, required fields, max lengths, numeric bounds, nullable flags, response schemas, and error shapes.

For simple repeated read-only helper calls, cached knowledge is fine after checking it against the live schema during the current task. For writes, stop and report the schema/configuration problem if the schema cannot be fetched unless the user explicitly tells you to proceed from known docs.

API-only rule

For Open Plantbook plant data and plant operations, use only API-backed paths:

• scripts/openplantbook_cli.py search ...
• scripts/openplantbook_cli.py detail ...
• scripts/openplantbook_cli.py create --from-dossier ...
• direct HTTP calls matching the live OpenAPI schema

Do not use public Browse DB pages, web fetch, browser automation, HTML scraping, or search-engine snippets as a fallback for Open Plantbook plant data. If the helper cannot authenticate or an API call fails, stop and report the API/configuration error.

Do not recover credentials from backups, session transcripts, shell history, logs, browser storage, or other stale/private artifacts. Read credentials only from supported live sources.

Do not add or rely on an environment-selected API base URL. The helper uses the official Open Plantbook API host so Open Plantbook API keys and OAuth client secrets are not sent to a caller-selected host.

Credentials

Read-only helper authentication can use either:

• OPENPLANTBOOK_API_KEY for token auth
• OPENPLANTBOOK_CLIENT_ID and OPENPLANTBOOK_CLIENT_SECRET for OAuth bearer auth
• OPENPLANTBOOK_OAUTH_CREDENTIALS for bundled OAuth credentials

Use OAuth bearer auth for write operations unless the live schema later says token auth supports them.

Do not treat OPENPLANTBOOK_CLIENT_ID as a standalone API key. Do not print secrets, echo secrets, write secrets into files, or include secrets in user-visible output.

If a UI or hub card exposes one secret field, label it as Open Plantbook credential, not API key. Accept these user-facing forms:

• Plain API key: use as OPENPLANTBOOK_API_KEY. This supports read/search/detail workflows only unless the live schema later permits token-auth writes.
• JSON OAuth bundle: {"client_id":"...","client_secret":"..."}. Prefer this form for OAuth because it is self-describing and does not need escaping.
• OAuth shorthand: client_id:client_secret. Support this only as a convenience fallback; parse on the first colon and prefer JSON in docs/examples.

Keep environment variable names stable. Store OAuth bundles in OPENPLANTBOOK_OAUTH_CREDENTIALS, or store split OAuth values in OPENPLANTBOOK_CLIENT_ID and OPENPLANTBOOK_CLIENT_SECRET.

Supported helper credential sources, in order:

1. Process environment variables.
2. Explicit private env file via OPENPLANTBOOK_ENV_FILE=/path/to/openplantbook.env.

Agent-specific adapters may map their own secret stores to these environment variables. Keep platform-specific secret paths and config formats in adapter documentation, not in this canonical skill.

The private env file should contain plain KEY=value lines. The helper parses this file directly and does not execute it as shell code. Example OAuth bundle:

text

OPENPLANTBOOK_OAUTH_CREDENTIALS={"client_id":"...","client_secret":"..."}

Plant operations

The live schema verified for API version 202606 lists these plant operations:

• GET /api/v1/plant/search
• GET /api/v1/plant/detail/{pid}/
• POST /api/v1/plant/create
• PATCH /api/v1/plant/update
• DELETE /api/v1/plant/delete

Always re-check /api/schema/ before using these for writes or when field details matter.

Search plants

Use GET /api/v1/plant/search when the user asks to find plants by scientific name, alias, or common name.

Security in schema: OAuth read, cookie auth, or token auth.

Query parameters:

• alias: search text, minimum 3 characters unless userplant=true is used to list user plants.
• userplant: optional scope selector. true searches user plants only, false searches public plants only, omitted searches both with de-duplication where user plants supersede public matches.
• limit, offset: pagination.

Preferred helper path:

bash

python3 {baseDir}/scripts/openplantbook_cli.py search "abelia"

If constructing HTTP directly, encode UTF-8 safely and preserve pagination fields. The result may match common names without telling you which field matched, so mention potential ambiguity when names look surprising.

Retrieve plant details

Use GET /api/v1/plant/detail/{pid}/ when the user asks for details, thresholds, care fields, common names, or a specific PID.

Security in schema: OAuth read, cookie auth, or token auth.

Parameters:

• pid path parameter, required.
• lang query parameter: optional 2-letter ISO 639-1 code or regional tag such as en-GB / pt_BR.
• include query parameter: optional extra categories such as care, care,poison, or * when supported by the schema.

Preferred helper path:

bash

python3 {baseDir}/scripts/openplantbook_cli.py detail "abelia chinensis" --lang en --include care

If the caller has a user plant with the PID, the customized user plant is returned with user_plant: true; otherwise the public plant is returned.

Create user plant

Use POST /api/v1/plant/create only when the user explicitly asks to create a new Open Plantbook user plant or push a plant dossier into Open Plantbook.

Security in schema: OAuth read write, or cookie auth. Do not use token auth for create unless the schema later says it supports it.

Request schema:

• Resolve #/components/schemas/PlantCreateRequest from /api/schema/.
• display_pid is required.
• pid, user, and common_names are server-managed or unsupported for create and should not be supplied.
• A plant that already exists in public DB or the caller profile returns conflict; update it instead.

Observed schema limits for API 202606:

• display_pid: string max 100, required.
• alias: string max 100, nullable.
• category: string max 100, nullable.
• sunlight: string max 200, nullable.
• watering: string max 200, nullable.
• fertilization: string max 250, nullable.
• pruning: string max 200, nullable.
• soil: string max 150, nullable.
• origin: string max 100, nullable.
• Threshold fields such as min_temp, max_temp, min_light_lux, max_light_lux, min_env_humid, max_env_humid, min_soil_moist, max_soil_moist, min_soil_ec, max_soil_ec, min_light_mmol, and max_light_mmol: nullable int64 with schema numeric bounds.

Use direct HTTP with a stable API client user agent:

text

openplantbook-agent-skill/1.0 (+https://open.plantbook.io/docs/)

A live urllib request without an explicit user agent was blocked by Cloudflare with Error 1010.

For dossier-based creation, prefer the helper:

bash

python3 {baseDir}/scripts/openplantbook_cli.py create --from-dossier plant_dossiers/chlorophytum_orchidastrum.json

The dossier JSON must already use PlantCreateRequest field names. The helper does not rename legacy dossier fields such as min_temp_c or min_soil_ec_uScm; fields that are not in the live create schema are ignored and reported. It validates types and numeric bounds, requires display_pid, and truncates overlong string fields to schema maxLength for the outgoing payload unless --no-truncate is supplied.

Do not map PPFD fields into min_light_mmol / max_light_mmol unless the dossier explicitly stores Open Plantbook-compatible mmol values. PPFD in umol/m2/s is not the same field.

Before creating, summarize the chosen source dossier and generated payload keys. If the user has already explicitly asked to create the plant, proceed; otherwise ask for confirmation because this is a write action to an external service.

Report results without secrets:

• 201: created successfully; include returned pid/identifier if present.
• 409: plant already exists in user or main DB; report duplicate rather than retrying; use update if the user wants changes.
• 400: validation error; summarize API error details and payload keys, not credentials. If schema max lengths explain the failure, shorten or omit offending text fields once and retry if the user already asked to create.
• 429: report throttling and server-provided wait time; do not retry until that time has passed.
• Auth errors: report credential configuration/authentication failure without printing secret values.

Update plant

Use PATCH /api/v1/plant/update when the user asks to modify an existing user plant or customize a public plant into the caller profile.

Security in schema: OAuth read write, or cookie auth.

Request schema:

• Resolve #/components/schemas/PatchedPlantUpdateRequest from /api/schema/.
• pid is required by endpoint behavior even if the patch schema itself marks all fields optional.
• At least one plant attribute besides pid must be supplied.
• Only PATCH is supported. PUT is not supported and can return 405.

Behavior:

• If pid refers to a user plant, that user plant is updated.
• If pid refers to a public plant, Open Plantbook clones it into the caller profile and applies the requested changes to that copy.
• Public plants are not modified in place.

Use schema max lengths and nullable flags exactly as for create. Shorten long care text before sending, or omit optional fields that cannot be safely shortened.

Confirm before updating unless the user explicitly gave the target PID and fields or explicitly asked to update from a named dossier/file.

Report results without secrets:

• 200: update successful; include returned pid, display_pid, and user_plant if present.
• 400: validation error; summarize field-level errors.
• 404: PID exists neither in user nor public plants.
• 405: method unsupported, usually from using PUT instead of PATCH.
• 429: throttled; report wait time and stop.
• 500: report server error and avoid blind retries.

Delete user plant

Use DELETE /api/v1/plant/delete only when the user explicitly asks to delete a user plant.

Security in schema: OAuth read write, or cookie auth.

Request schema:

• Resolve #/components/schemas/PlantDeleteRequest from /api/schema/.
• Required field: pid.
• pid is case-sensitive.

Behavior:

• Deletes a plant from the caller profile only.
• Public plants cannot be removed.
• Known schema/docs issue: omitted pid may return 404 rather than 400 because the missing value is used as the lookup key.

Always confirm destructive deletes unless the user's message already includes an explicit delete instruction and an exact PID. For ambiguous names, search/detail first and ask for the exact PID.

Report results without secrets:

• 204: deleted successfully.
• 404: user plant not found, public plant cannot be deleted, or pid omitted.
• 429: throttled; report wait time and stop.

Advanced sensor-upload integration

Sensor upload is an advanced developer integration topic, not a headline skill workflow. Do not present sensor upload as a general agent feature, and do not infer plant-health/status answers from uploaded sensor history unless Open Plantbook exposes a read/status API for that data.

When explicitly asked to help build or debug an Open Plantbook sensor uploader:

• Fetch /api/schema/ before building payloads.
• Use OAuth read write; do not use token auth unless the schema later permits it.
• Register the plant instance first with POST /api/v1/sensor-data/instance, binding pid plus a device/app custom_id.
• Use the returned plant-instance UUID in JTS upload columns; sensor upload binds to the instance UUID, not directly to the plant PID.
• Upload JSON Time Series data to POST /api/v1/sensor-data/upload; use dry_run=true while testing integrations.

Publishing and maintenance

When preparing this skill for ClawHub/OpenClaw Hub publication, read {baseDir}/references/publish-notes.md for the package checklist, suggested listing copy, validation commands, and release command template.

• Validate supported measurement names and units before upload: temp in deg C, soil_ec in uS/cm, env_humid in %, soil_moist in %, and light_lux in lux.
• Preserve ISO 8601 timestamps with timezone offsets.
• Avoid uploading bogus values. Preserve privacy: include location only when the user explicitly opted in.

Safety and privacy

• Treat plant database output as informational plant-care guidance, not medical, veterinary, food-safety, or toxicity advice.
• Do not identify plants from images with Open Plantbook unless paired with a plant-identification tool.
• For pet/child safety, verify toxicity with an authoritative source before making strong claims.
• Never expose Open Plantbook credentials.
• Respect rate limits; back off on HTTP 429 and use Retry-After or the API error wait time when present.

Helper CLI

This skill folder includes scripts/openplantbook_cli.py for quick CLI workflows:

bash

python3 skills/openplantbook/scripts/openplantbook_cli.py search "abelia"
python3 skills/openplantbook/scripts/openplantbook_cli.py detail "abelia chinensis" --lang en --include care
python3 skills/openplantbook/scripts/openplantbook_cli.py create --from-dossier plant_dossiers/chlorophytum_orchidastrum.json --dry-run

The helper is direct-HTTP only. It does not depend on openplantbook-sdk. It supports read-only search/detail plus OAuth-backed create --from-dossier; use schema-backed direct HTTP for update/delete and advanced integration tasks.

Do not use public Open Plantbook HTML pages, web fetch, or browser automation as fallback for helper failures.

Output style

Give concise, practical plant-care answers. Include raw JSON only when the user asks for API/debug output. When multiple matches are returned, ask the user to choose only if there is real ambiguity; otherwise pick the best API match and mention that it was the best API match.