Puddle developer resources

This page describes only Puddle interfaces that are intentionally public. The current public API contract covers service health and read-only retrieval of cached free plans; it does not grant access to private family data or internal AI operations. Do not infer an endpoint, authentication method, or capability that is absent from the OpenAPI document.

API versioning and deprecation policy

Puddle public API v1 uses /api/v1/healthz and /api/v1/free-plan/{ageBand}/{personaId}. Existing /api URLs remain compatible. Additive fields may appear within v1; clients should ignore unknown fields. Breaking changes require a new major URL version. No version is currently deprecated. Before a planned retirement, Puddle will publish migration guidance here and send a Deprecation header (RFC 9745) and Sunset header (RFC 8594) on affected responses with at least 90 days' notice. Urgent security or privacy restrictions may take effect sooner.

Puddle read-only CLI

Download /puddle-cli.mjs and inspect it before running with Node.js 20 or newer. Run node puddle-cli.mjs --help, health, contract, or plan elementary maker. The CLI only reads public data from askpuddle.com; it does not sign in, send family data, purchase anything, or generate plans. It is distributed directly from this website, not yet published to npm, PyPI, or Homebrew.

Contract and calling guidance

The canonical machine-readable contract is available at /api/openapi.json and uses the /api base path. Read that contract before calling an operation. Health and cached free-plan retrieval require no authentication. Free-plan requests use only the age-band and persona values listed in OpenAPI and do not generate a new plan. No public family-data write API or MCP server is advertised.

Errors, limits, and caching

API errors use JSON with a stable code, human-readable message, and actionable hint. Callers should inspect the HTTP status and error body rather than retrying every failure. RateLimit headers describe the applicable window when present; on HTTP 429, honor Retry-After. Public HTML resources can be requested as text/markdown with Accept: text/markdown, and negotiated responses vary on Accept.

Minimal health request

Send GET /api/healthz with Accept: application/json. A successful response is JSON described by the OpenAPI response schema. Health status confirms service availability only; it does not authenticate a user or expose product data.