Documentation

Base URL

https://api.theholisticcare.com/v1

Authentication

None. This is a free, public, read-only API. No API key or signup required.

Pagination

List endpoints accept limit (default 20, max 100) and offset (default 0) query params. The response's pagination object reports total matching records. Omitting either param entirely is never an error — you get the default. But a present, malformed value (non-numeric, non-integer, a limit ≤ 0, or a negative offset) returns a clean 400 invalid_parameter rather than silently falling back, so a typo in your integration surfaces immediately instead of quietly returning the default page. The one deliberate exception: limit above the documented max of 100 is not an error — it is silently clamped to 100, since asking for “too many” isn’t a mistake the same way asking for a negative or non-numeric amount is.

?limit=abc, ?limit=-1, and ?offset=-1 all return 400. ?limit=10000 returns 200 with limit: 100 in the response.

Caching

Every response carries a Cache-Control header, set per endpoint family against how often that data actually changes — not one blanket value:

Tier	Header	Used by
None	`no-store`	`/health` — must always reflect the live process.
Short	`public, s-maxage=300, stale-while-revalidate=3600`	`/v1/search` — arbitrary `q` values mean there's no real hit rate to protect, so freshness is favored.
Standard	`public, s-maxage=3600, stale-while-revalidate=86400`	Every other list/detail endpoint (blog, glossary, whitepapers, mindfulness-games, practices, `/v1/resources`). A 1-hour edge cache matches how often Sanity content actually publishes.
Long	`public, s-maxage=86400, stale-while-revalidate=604800`	`/v1/categories` (a derived taxonomy) and `/v1/panchavikas/resources` (a marketing-copy singleton that changes on the order of weeks, not hours).

This means a change published in Sanity can take up to an hour to appear through the API for standard-tier endpoints (up to a day for long-tier). If you need to confirm you're seeing the latest data, check the response's meta.generated_at timestamp.

Rate limiting

Requests are throttled to a best-effort ~60 requests/minute per IP address, returning 429 rate_limited when exceeded.

This limit is enforced in-memory, per serverless instance — it is a genuine deterrent against casual abuse, but it is not a hard, platform-wide guarantee. A client whose requests happen to land across multiple warm instances, or who arrives right after an instance cold-starts, may see a higher effective ceiling in practice. See RATE_LIMITING.md for the full honest assessment and what a stronger, distributed limiter would require. If you need a specific volume for a legitimate integration, contact us first (see Support below) rather than building against an assumed exact threshold.

CORS

Every endpoint sends Access-Control-Allow-Origin: * — this is a genuinely public, read-only API, so there is no per-origin allow-list to request access to. Cross-origin GET requests work from any website or client with no configuration on your end. OPTIONS preflight requests are handled on every route and return a 204 with the same permissive headers. No credentials (cookies, auth headers) are used or required, and none are echoed back.

GET /v1/whitepapers

Research citations behind The Holistic Care's content, one per real published study.

curl "https://api.theholisticcare.com/v1/whitepapers?topic=meditation&limit=10"

Query params: topic (mindfulness, meditation, yoga, sleep, nonduality, children, anxiety, physiology), study_type (rct, meta-analysis, observational, cohort, clinical-trial, physiological, guideline).

{
  "id": "research:goyal-2014-meditation-programs",
  "slug": "goyal-2014-meditation-programs",
  "type": "research_citation",
  "title": "Meditation Programs for Psychological Stress and Well-Being",
  "authors": "Goyal M, Singh S, Sibinga EMS, et al.",
  "year": 2014,
  "journal": "JAMA Internal Medicine",
  "study_type": "meta-analysis",
  "sample_size": "3,515 participants across 47 trials",
  "topic": "mindfulness",
  "summary": "...",
  "key_finding": "...",
  "limitations": "...",
  "source_url": "https://...",
  "updated_at": "2026-..."
}

GET /v1/whitepapers/:slug

Same shape as above, plus related_posts and related_terms arrays.

GET /v1/glossary

Plain-language definitions of mindfulness/yoga/nonduality terms.

curl "https://api.theholisticcare.com/v1/glossary?pillar=nonduality"

Query param: pillar (nonduality, yoga, meditation, kundalini, ayurveda, general-wisdom).

{
  "id": "glossary:pranayama",
  "slug": "pranayama",
  "type": "glossary_term",
  "title": "Pranayama",
  "pillar": "yoga",
  "summary": "...",
  "etymology": "Sanskrit: ...",
  "also_known_as": ["..."],
  "updated_at": "2026-..."
}

GET /v1/glossary/:slug

Same shape, plus extended_explanation (a small portable-text block array), related_terms, and related_posts.

GET /v1/mindfulness-games

All 16 free, browser-based mindfulness games hosted on theholisticcare.com — no download, no app, no account.

curl "https://api.theholisticcare.com/v1/mindfulness-games?audience=children"

Query params: audience (children, teens, adults, educators, parents), skill (attention, body-awareness, breathwork, cognitive-reframing, emotional-regulation, gratitude, grounding, loving-kindness, mindful-listening, nondual-awareness, relaxation, self-compassion, sleep).

{
  "id": "MG-001",
  "slug": "breathing-buddy",
  "type": "mindfulness_game",
  "api_id": "MG-001",
  "title": "Breathing Buddy",
  "url": "https://www.theholisticcare.com/games/breathing-buddy.html",
  "icon": "🫧",
  "tag": "Breathing",
  "description": "...",
  "free": true,
  "keywords": ["..."],
  "audiences": ["children"],
  "age_min": 5,
  "age_max": 12,
  "duration_minutes": 5,
  "skills": ["breathwork"],
  "updated_at": "2026-..."
}

GET /v1/mindfulness-games/:slug

Same shape as above, for a single game.

GET /v1/practices

All 111 free guided-audio practices from The Holistic Care's Stillness Library, each with a direct link to the MP3 file (hosted on Cloudflare R2 — this API never proxies the audio itself). The Stillness Library also has 47 paid tracks; those are never exposed by this endpoint or anywhere else in this API.

curl "https://api.theholisticcare.com/v1/practices?category=sleep"

Query param: category (mindfulness, children, breathwork, nondual-awareness, yoga-nidra, students, sleep).

{
  "id": "SL-041",
  "slug": "letting-go-of-the-day",
  "type": "practice",
  "track_id": "SL-041",
  "title": "Letting Go of the Day",
  "category": "sleep",
  "excerpt": "...",
  "audio_url": "https://files.theholisticcare.com/stillness-library-free/letting-go-of-the-day.mp3",
  "read_time_minutes": 6,
  "canonical_url": "https://www.theholisticcare.com/stillness-library/letting-go-of-the-day",
  "updated_at": "2026-..."
}

GET /v1/practices/:slug

Same shape as above, plus a related_practices array (free practices only).

GET /v1/blog

Metadata and excerpts for 527 published blog posts from theholisticcare.com. Blog endpoints expose metadata/excerpts only. Full article content remains on the canonical The Holistic Care website — this API never returns article body, images, author details, or category internals.

curl "https://api.theholisticcare.com/v1/blog?tag=mindfulness&limit=10"

Query params: tag (matches against the post's tags), q (free-text search across title, excerpt, and tags only — never the article body).

{
  "title": "Mindfulness for Anxiety: A Complete Guide",
  "excerpt": "...",
  "tags": ["mindfulness", "anxiety"],
  "canonical_url": "https://www.theholisticcare.com/blog/mindfulness-for-anxiety"
}

Note: unlike every other resource in this API, blog objects deliberately do NOT include id, slug, type, or updated_at — the response shape is intentionally minimal.

GET /v1/blog/:slug

Same shape as above, for a single post. A nonexistent, unpublished, or private slug returns a normal 404 — never a different error that would reveal a draft exists.

GET /v1/panchavikas/resources

The public-facing side of PanchaVikas, The Holistic Care's early-years framework: the 5 pathway summaries (Prithvi, Jal, Agni, Vayu, Akash) plus the framework guide PDF download. This endpoint deliberately does not expose FAQs, school pricing tiers, or any curriculum/session-plan content — none of that exists in this API's data source at all. Not paginated (6 fixed items).

curl "https://api.theholisticcare.com/v1/panchavikas/resources"

{
  "data": [
    {
      "id": "PV-pathway-prithvi",
      "type": "panchavikas_pathway",
      "title": "Prithvi",
      "summary": "Ground & Grow: Body, senses, stability, health, independence and nature connection.",
      "source_url": "https://www.theholisticcare.com/panchavikas"
    },
    {
      "id": "PV-guide",
      "type": "panchavikas_download",
      "title": "PanchaVikas Early Years Framework Guide",
      "summary": "The public guide to the philosophy, five pathways, mindfulness layer, age progression and school implementation model.",
      "download_url": "https://www.theholisticcare.com/downloads/panchavikas-framework-guide.pdf",
      "source_url": "https://www.theholisticcare.com/panchavikas/framework-guide"
    }
  ]
}

GET /v1/resources

Browse every genuinely public resource family on theholisticcare.com through one normalized shape, rather than calling six endpoints separately. This is a discovery/browse layer — call the dedicated endpoint above for a family's full field set (e.g. a game's age_min/age_max are richer on /v1/mindfulness-games directly). Every field not applicable to a given family's type is null rather than guessed at.

curl "https://api.theholisticcare.com/v1/resources?type=mindfulness_game&audience=children&limit=5"

Query params: type (blog, mindfulness_game, guided_practice, research, glossary, panchavikas_pathway, panchavikas_download — omit to search all types), category, audience, skill, age_min, age_max (only resources with real, populated age data participate in an age filter — currently just mindfulness_game).

{
  "id": "MG-001",
  "title": "Breathing Buddy",
  "slug": "breathing-buddy",
  "type": "mindfulness_game",
  "summary": "...",
  "category": "Breathing",
  "tags": ["..."],
  "audiences": ["children"],
  "age_min": 5,
  "age_max": 12,
  "duration_minutes": 5,
  "skills": ["breathwork"],
  "access": "free",
  "source_url": "https://www.theholisticcare.com/games/breathing-buddy.html",
  "updated_at": "2026-..."
}

id is populated for every resource here (never null), using each family's existing stable public identifier where one exists (MG-* for games, SL-* for practices, PV-* for PanchaVikas), or a deterministic type:slug pair otherwise (blog:<slug>, research:<slug>, glossary:<slug>) — never a raw Sanity _id. slug is populated for every type except panchavikas_pathway/panchavikas_download, which have no real slug and are always null there. A blog-type resource here still always has category: null (blog posts have no equivalent taxonomy field), but note this is richer than the dedicated /v1/blog endpoint itself, which omits id/slug/type/updated_at entirely.

{
  "id": "blog:i-am-that-nisargadatta",
  "title": "I Am That: Nisargadatta Maharaj's Teaching on the Sense of \"I Am\"",
  "slug": "i-am-that-nisargadatta",
  "type": "blog",
  "summary": "...",
  "category": null,
  "tags": ["nonduality", "self-inquiry"],
  "access": "free",
  "source_url": "https://www.theholisticcare.com/blog/i-am-that-nisargadatta",
  "updated_at": null
}

GET /v1/search

Free-text, case-insensitive substring search across the same 6 families' public metadata only (title, summary, category, tags) — never article bodies, private fields, or premium content, none of which exist in the searched data in the first place. Not built on Elasticsearch, Algolia, or embeddings — a simple in-memory match over public metadata, correct and fast at current content volumes (~750 public records total). q is required.

curl "https://api.theholisticcare.com/v1/search?q=breathing&limit=5"

Response shape is identical to /v1/resources — the same normalized Resource objects, filtered by match instead of by type/category.

Returns 400 missing_query if q is absent or empty.

GET /v1/categories

Distinct topic values in use across whitepapers and pillar values in use across the glossary — a lightweight way to build a filter UI without guessing valid values.

Errors

Every error responds with the same envelope: { "error": { "code": "...", "message": "..." } } — always valid JSON, never an HTML error page, and never a stack trace or internal implementation detail.

Status	code	Meaning
`400`	`missing_query`	`/v1/search` without a `q` parameter.
`400`	`invalid_type`	`/v1/resources` with a `type` value outside the supported list.
`400`	`invalid_parameter`	A malformed `limit` or `offset` value on any list endpoint. See Pagination above.
`404`	`not_found`	No public record exists at that slug.
`429`	`rate_limited`	Too many requests from this IP recently. See Rate limiting above.
`500`	`internal_error`	Something went wrong server-side. Safe to retry.

A note on record IDs

Record IDs are stable, public identifiers, never internal CMS document IDs. Games use MG-001 style IDs, guided practices use SL-015 style IDs, PanchaVikas resources use PV-*, and glossary terms, research summaries and blog posts use glossary:<slug>, research:<slug> and blog:<slug> (the blog prefix appears on unified /v1/resources and /v1/search results; /v1/blog itself returns discovery fields only). slug remains the lookup key for detail endpoints.

Versioning

This is /v1. Additive, backwards-compatible changes (new endpoints, new optional fields, new optional query params) can land in /v1 at any time without notice. A breaking change (removing or renaming a field, changing a field's type or meaning, or removing an endpoint) will only ever ship as a new /v2, with /v1 left running unchanged. See VERSIONING.md for the full policy.

Licensing & usage terms

This API is free to use and read-only. There is no signup, no key, and no cost. There are four separate things going on here — don't assume one implies another:

Software license (the code in this repo): MIT. See LICENSE.
API access terms (calling the live endpoint): free, public, read-only, no auth for current endpoints, subject to fair-use expectations. See USAGE.md.
Content rights (the data this API returns): Copyright © The Holistic Care, all rights reserved, unless an individual resource explicitly states otherwise. The MIT code license above does not extend to this content — it is not Creative Commons, and free API access does not grant redistribution or commercial-reuse rights over the underlying mindfulness content, research summaries, glossary entries, games, practices, or PanchaVikas materials.
Attribution: recommended, not required — see below.

Full detail on all four is in LICENSING.md.

Attribution

Attribution is appreciated, not required. If you do credit the source, "Source: The Holistic Care, https://www.theholisticcare.com" (linking the specific canonical_url/source_url a record returns, where one is relevant) is all we ask for — see ATTRIBUTION.md for the full guidance. No specific link format, badge, or backlink placement is required.

Support

This is a small, independently-run API, not a commercial product with an SLA. For questions, a bug report, or a legitimate high-volume use case you'd like to discuss ahead of time, open an issue on the GitHub repository.

← Back to overview