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.

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.