API Reference · v1

Developer documentation

Authentication, quota behaviour, the error contract and every endpoint — generated from the same source of truth as the OpenAPI document, so neither can drift.

Get a key openapi.json GET /api/v1

Step 1

Authentication

One key, sent in a header. Create keys in the dashboard — they are stored hashed, so the plaintext is shown exactly once at creation.

# preferred
curl -H "x-api-key: $API_KEY" https://www.royalfitnesclub.in/health/api/v1/plans

# also accepted
curl -H "Authorization: Bearer $API_KEY" https://www.royalfitnesclub.in/health/api/v1/literature/search?q=diabetes

A query-string fallback (?api_key=) exists for quick browser tests only — do not use it in production, where URLs are logged.

Step 2

Response envelope

Success and failure share one predictable shape, so you write one parser.

HTTP/1.1 200 OK
x-plan: free
x-ratelimit-limit-day: 1000
x-ratelimit-remaining-day: 999
x-ratelimit-reset: 2026-09-14T00:00:00.000Z

{
  "ok": true,
  "meta": { "plan": "free", "quota": { … } },
  "data": { "results": [ … ], "total": 128 }
}

HTTP/1.1 429 Too Many Requests
retry-after: 3600

{
  "ok": false,
  "error": {
    "code": "quota_exceeded",
    "message": "Daily quota reached for the Free plan…",
    "docs": "https://…/developers/docs",
    "status": 429
  }
}

Step 3

Quotas & rate limits

Two limits per key, both echoed in headers: a daily allowance and a per-minute burst limit. Quotas reset at UTC midnight.

Plan	Per day	Per minute	Bulk export	Attribution
Free	1,000	30	—	Required
Starter	50,000	120	—	Not required
Pro	5,00,000	600	Yes	Not required
Enterprise	Unlimited	Unlimited	Yes	Not required

Bulk export — Pro & Enterprise

GET /api/v1/export/{dataset}?q=millet&format=csv|jsonl&limit=500 pages the upstream and returns a real file download — RFC-4180 CSV or JSON Lines — for the food, literature and exercises datasets. Provenance travels with the file in X-Export-Source, X-Export-License and X-Export-Attribution headers, while X-Export-Live and X-Export-Notice tell you whether upstream actually answered — an unreachable source yields a file with no rows, never fabricated zeros. Lower plans receive 403 plan_upgrade_required.

Console

Subscriptions & billing

Self-serve plans are settled through the payment provider abstraction. These endpoints use your account cookie, never an API key — a key can read data, it cannot move money.

Endpoint	Purpose	Notes
GET`/health/api/v1/keys`	List API keys	List the signed-in account's keys (prefixes only — plaintext keys are never returned).
POST`/health/api/v1/keys`	Create API key	Create a key for the signed-in account. The plaintext key is returned exactly once.
DELETE`/health/api/v1/keys/{keyId}`	Revoke API key	Permanently revoke a key. Usage history is retained, the key stops working immediately.
GET`/health/api/v1/billing/subscription`	Subscription & billing state	The signed-in account's effective plan, subscription history and whether the configured payment provider can attest a real charge. Reports mode: "simulated" when running on the sandbox provider.
POST`/health/api/v1/billing/checkout`	Start a subscription checkout	Creates a provider order and a pending (past_due) subscription for the Starter or Pro plan. Nothing is upgraded until the payment is verified, so an abandoned checkout cannot grant quota.
POST`/health/api/v1/billing/verify`	Settle a subscription payment	Verifies a payment with the provider and activates the subscription, upgrading every active key on the account. Refused unless the payment is attested (or the sandbox provider is explicitly in use, which is recorded as demo: true).
DELETE`/health/api/v1/billing/subscription`	Cancel a subscription	Cancels a subscription and returns the account's active keys to the Free plan. Defaults to the account's active subscription when subscriptionId is omitted.

When a plan is actually granted

Creating a checkout does not upgrade you: the subscription is created aspast_due and quota stays on the Free plan until a payment is settled. A plan moves only when the provider confirms the charge — either with a verified signature from a provider that holds real secrets, or on the sandbox provider, where the activation is recorded withdemo: true and counted as zero revenue.

Cancelling returns every active key on the account to the Free plan immediately, so cancelled subscriptions cannot keep spending paid quota. Keys created while a subscription is active inherit its plan; the plan in a request body is ignored on purpose, so a client can never promote itself.

Reference

Error codes

Codes are stable — branch on them rather than on the message text.

Code	HTTP	When	What to do
`missing_api_key`	401	No x-api-key header and no Authorization bearer token.	Send your key in the x-api-key header.
`invalid_api_key`	401	The key is unknown, revoked, or belongs to a deleted account.	Check for stray whitespace, or create a new key in the dashboard.
`quota_exceeded`	429	The plan's daily request allowance is used up.	Wait for X-RateLimit-Reset (UTC midnight) or upgrade the plan.
`rate_limited`	429	The per-minute burst limit was exceeded.	Retry after the number of seconds in Retry-After; back off exponentially.
`invalid_request`	400	A required parameter is missing or out of range.	Check the parameter table for the endpoint.
`not_found`	404	No such API key on your account (delete), or no matching record.	Verify the identifier.
`upstream_unavailable`	503	A live upstream source is unreachable and an empty answer would mislead (air quality).	Retry shortly; the endpoint is cached once the source recovers.
`plan_upgrade_required`	403	The endpoint needs a capability your plan does not include (bulk export).	Upgrade to Pro, or fetch the same data in pages within your plan's quota.
`unauthorised`	401	A console endpoint was called without a signed-in session.	Keys and billing use your account cookie, not an API key — sign in on the dashboard.
`payment_not_attested`	402	A subscription payment could not be verified, so no plan change was applied.	Check the payment provider's response — a plan is granted only on an attested charge.
`payment_provider_unconfigured`	503	Real billing is enabled (PAYMENT_PROVIDER=razorpay) but its secrets are missing.	Set the Razorpay keys, or unset PAYMENT_PROVIDER for the sandbox. The API refuses the sale rather than silently simulating it.
`internal_error`	500	Unexpected server-side failure.	Retry; if it persists, contact support with the timestamp and endpoint.

Reference

13 data endpoints

Parameters, sample payloads and — importantly — the upstream source and licence you must honour.

GET/health/api/v1/food/searchx-api-key

Food search

Search packaged and branded foods with per-100g nutrition, Nutri-Score and NOVA group.

Param	Type	Required	Description
`q`	string	Yes	Food name or brand e.g. millet
`limit`	integer	No	Number of results to return (1–20, default 10). e.g. 10

Source: Open Food Facts + USDA FoodData Central · Licence: ODbL + DBCL (USDA: public domain)

{
  "results": [
    {
      "id": "8901491101727",
      "name": "Ragi Flour",
      "nutrients": {
        "calories": 328,
        "protein": 7.3
      }
    }
  ],
  "total": 42
}

GET/health/api/v1/exercisesx-api-key

Exercise library

Strength and mobility exercises with muscles, equipment and instructions.

Param	Type	Required	Description
`q`	string	Yes	Exercise, muscle or equipment e.g. squat
`limit`	integer	No	Number of results to return (1–20, default 10). e.g. 10

Source: wger Workout Manager · Licence: AGPL-3.0

{
  "results": [
    {
      "id": 123,
      "name": "Barbell Squat",
      "muscles": [
        "Quadriceps"
      ]
    }
  ]
}

GET/health/api/v1/clinical-trialsx-api-key

Clinical trials

Registered interventional and observational trials, with phase, status and locations.

Param	Type	Required	Description
`q`	string	Yes	Condition or intervention e.g. diabetes
`limit`	integer	No	Number of results to return (1–20, default 10). e.g. 10

Source: ClinicalTrials.gov · Licence: Public domain (US NLM)

{
  "results": [
    {
      "nctId": "NCT01234567",
      "title": "…",
      "phase": "PHASE3"
    }
  ]
}

GET/health/api/v1/literature/searchx-api-key

Medical literature search

Peer-reviewed life-science literature with abstracts, journal, year and citation counts.

Param	Type	Required	Description
`q`	string	Yes	Search terms (PICO-style supported) e.g. millet glycemic control
`limit`	integer	No	Number of results to return (1–25, default 10). e.g. 10

Source: Europe PMC · Licence: Open (Europe PMC terms; abstracts per publisher)

{
  "results": [
    {
      "id": "MED:12345678",
      "title": "…",
      "journal": "Lancet",
      "year": 2024,
      "citedByCount": 12
    }
  ],
  "total": 128
}

GET/health/api/v1/scholarly/searchx-api-key

Scholarly works

Open scholarly catalogue: works, authors, institutions and open-access links.

Param	Type	Required	Description
`q`	string	Yes	Topic, title or author e.g. intermittent fasting insulin
`limit`	integer	No	Number of results to return (1–25, default 10). e.g. 10

Source: OpenAlex · Licence: CC0 1.0

{
  "results": [
    {
      "id": "W2741809807",
      "title": "…",
      "year": 2023,
      "citedByCount": 88
    }
  ]
}

GET/health/api/v1/nutrition/fruitx-api-key

Fruit nutrition

Per-100g energy, sugar, fibre and micronutrients for fruits.

Param	Type	Required	Description
`name`	string	Yes	Fruit name e.g. mango

Source: Fruityvice · Licence: Open data

{
  "name": "Mango",
  "nutrients": {
    "calories": 60,
    "carbohydrates": 15,
    "sugar": 13.7
  }
}

GET/health/api/v1/air-qualityx-api-key

Air quality

Current PM2.5, PM10, ozone, NO2 and European AQI for any coordinate — health advisories included.

Param	Type	Required	Description
`lat`	number	Yes	Latitude (-90…90). e.g. 28.6139
`lon`	number	Yes	Longitude (-180…180). e.g. 77.2090

Source: Open-Meteo Air Quality · Licence: CC BY 4.0 (non-commercial tiers)

{
  "location": {
    "lat": 28.6139,
    "lon": 77.209
  },
  "aqi": {
    "european_aqi": 168,
    "level": "Unhealthy"
  },
  "pollutants": {
    "pm2_5": 96.4
  }
}

GET/health/api/v1/indicatorsx-api-key

Health indicators

Country-level health and development indicators (life expectancy, health spend, mortality).

Param	Type	Required	Description
`country`	string	No	ISO-2 country code (default IN). e.g. IN
`indicator`	string	No	World Bank indicator code. e.g. SP.DYN.LE00.IN

Source: World Bank Open Data · Licence: CC BY 4.0

{
  "country": "IN",
  "indicator": "SP.DYN.LE00.IN",
  "value": 70.4,
  "year": 2023
}

GET/health/api/v1/providersx-api-key

Provider directory

Every upstream data provider this API aggregates, with capabilities, licence and live status.

{
  "providers": [
    {
      "name": "openfoodfacts",
      "status": "AVAILABLE",
      "requiresKey": false
    }
  ]
}

GET/health/api/v1/usagex-api-key

Usage & quota

Current quota consumption for the key used on the request, with per-endpoint breakdown.

{
  "requestsToday": 42,
  "remainingToday": 958,
  "resetsAt": "2026-09-14T00:00:00.000Z"
}

GET/health/api/v1/healthcare-providersx-api-key

Healthcare provider directory

Search registered healthcare providers and organisations by name and state, with speciality, practice address and registration status. United States coverage (CMS NPPES) — stated explicitly so it is not mistaken for Indian provider data.

Param	Type	Required	Description
`q`	string	No	Provider or organisation name fragment. e.g. sharma
`state`	string	No	Two-letter state code. e.g. NY
`limit`	integer	No	Number of results (1–25, default 10). e.g. 10

Source: NPPES NPI Registry (CMS) · Licence: Public domain (US federal government work)

{
  "results": [
    {
      "id": "1234567893",
      "name": "ASHA SHARMA",
      "speciality": "Internal Medicine",
      "city": "ALBANY"
    }
  ]
}

GET/health/api/v1/outbreaksx-api-key

Outbreak reports

Latest WHO Disease Outbreak News reports, newest first, each with WHO's own publication date and a link to the full report. Filter by a country or disease word in the title.

Param	Type	Required	Description
`country`	string	No	Word to match in the report title (country or disease). Omit for all recent reports. e.g. congo

{
  "results": [
    {
      "id": "who-2026-don618",
      "title": "Ebola disease caused by Bundibugyo virus - Democratic Republic of the Congo",
      "publishedAt": "2026-09-25T15:30:18.000Z",
      "url": "https://www.who.int/emergencies/disease-outbreak-news/item/2026-DON618"
    }
  ]
}

GET/health/api/v1/export/{dataset}x-api-key

Bulk dataset export (Pro)

Download a dataset as RFC-4180 CSV or JSON Lines — food, literature or exercises. Requires the Pro or Enterprise plan; the response is a file, with provenance in X-Export-* headers. Returns 403 plan_upgrade_required on lower plans.

Param	Type	Required	Description
`dataset`	string	Yes	food \| literature \| exercises. e.g. food
`q`	string	Yes	Search terms for the dataset. e.g. millet
`format`	string	No	csv (default) or jsonl. e.g. csv
`limit`	integer	No	Rows to export (1–500, default 100). e.g. 100

Recipes

Client examples

Copy-paste starting points with retry-and-backoff handled.

// JavaScript — handles 429 with Retry-After
async function bhg(path, params = {}) {
  const url = new URL("https://www.royalfitnesclub.in/health" + path);
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));

  for (let attempt = 0; attempt < 4; attempt++) {
    const res = await fetch(url, { headers: { "x-api-key": process.env.BHG_API_KEY } });
    if (res.status === 429) {
      const wait = Number(res.headers.get("retry-after") ?? 60);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const body = await res.json();
    if (!body.ok) throw new Error(body.error.code + ": " + body.error.message);
    return body.data;
  }
  throw new Error("Rate limited after retries");
}

# Python
import os, requests

def bhg(path, **params):
    r = requests.get(
        "https://www.royalfitnesclub.in/health" + path,
        params=params,
        headers={"x-api-key": os.environ["BHG_API_KEY"]},
        timeout=15,
    )
    if r.status_code == 429:
        raise RuntimeError(f"Quota hit — retry after {r.headers.get('retry-after')}s")
    body = r.json()
    if not body.get("ok"):
        raise RuntimeError(body["error"]["code"])
    return body["data"]

print(bhg("/health/api/v1/nutrition/fruit", name="mango"))

Attribution & licence obligations

Each endpoint lists its upstream source and licence. You must attribute the upstream provider in your own UI where their licence requires it — for example "Air quality data by Open-Meteo(CC BY 4.0)". Plans that require attribution to Premium Health Platform echo the required string in meta.attribution on every response.

This API serves public reference data only. It is informational, not medical advice, and must not be used as the sole basis for diagnosis or treatment. See our disclaimer and terms.

Canonical URL: https://www.royalfitnesclub.in/developers/docs