# Ayurveda API, what to build and how to call it

> Ship a dosha profile that cites its verses, a morning routine anchored to the sunrise at the place the user names, or a seasonal guide that turns over on a real solar ingress, in under 30 minutes. No questionnaire.

A dosha quiz is a weekend of work and twenty consumer sites give one away. This domain is the other thing: 8 endpoints that COMPUTE. `POST /ayurveda/constitution` reads the vata, pitta and kapha shares from a verified sidereal birth chart and returns the chapter and verse behind every factor. `POST /ayurveda/dinacharya` computes brahma muhurta and the six dosha periods from the real sunrise at the place you send. `POST /ayurveda/ritucharya` resolves the season from actual solar ingress instants. Nothing here asks a user about their own body, and every response states its own scope.

## What you can build

- Dosha profile cards built from birth data, with the verse behind each factor shown beside the percentage
- Morning routine features where brahma muhurta is a real timestamp for the place the user names rather than a fixed 4 a.m.
- Dosha clock widgets that cut the actual day and the actual night into thirds, which is what a printed timetable cannot do
- Seasonal guides that turn over on the real ingress instant instead of on the first of the month
- Multi-domain companions that show the Ayurvedic reading beside the Vedic chart the app already fetched, on the same key
- Reference libraries for the three doshas, the fifteen sub-doshas, the six tastes and the twenty qualities, each row carrying its source
- Sanskrit-first study content for the German, French and Russian markets, where the vocabulary is already the working vocabulary and the gloss is what is missing
- Agent tools over Remote MCP: what does my chart say, when is brahma muhurta today, which season am I in, each answered with its citation

## Prerequisites

1. A RoxyAPI key from [/account](/account).
2. For the constitution: a `date`, a `time`, a `latitude` and a `longitude`, and optionally a `timezone`. The rising sign turns roughly every two hours and carries the heaviest weight, so the time is the input the reading is most sensitive to.
3. For the dinacharya and the daily reading: a `date`, a `latitude` and a `longitude`. No birth data, because the answer belongs to the place and the day rather than to a person.
4. For the ritucharya: a `date`, and nothing else.
5. Nothing at all for the three catalogue routes.
6. If you have a city name rather than coordinates, [`GET /location/search`](/api-reference#tag/location-and-timezone/GET/location/search) returns the latitude, longitude and IANA timezone on the same key.

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
composer require roxyapi/sdk
```

### .NET CLI
```bash
dotnet add package RoxyApi.Sdk
```

### Go
```bash
go get github.com/RoxyAPI/sdk-go
```

## Call the endpoint

The #1 Ayurveda call is the constitution. One POST turns birth data into the three shares and the verses behind them. Verified operationId: `calculateAyurvedicConstitution`.


### curl
```bash
curl -X POST https://roxyapi.com/api/v2/ayurveda/constitution \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 }'
```

### TypeScript SDK
```typescript
import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data: reading } = await roxy.ayurveda.calculateAyurvedicConstitution({
  body: {
    date: '1990-07-04',
    time: '10:12:00',
    latitude: 28.6139,
    longitude: 77.209,
    timezone: 'Asia/Kolkata',
  },
});

console.log(reading.composite.type);            // "pitta"
console.log(reading.composite.pitta);           // 87
console.log(reading.lagnaSign);                 // "leo"
console.log(reading.factors.length);            // 3
console.log(reading.factors[0].source.verse);   // "note to 20, the Satyacharya extract"
console.log(reading.conventions.signDoshaScheme); // "satyacharya"
```

### Python SDK
```python
import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

reading = roxy.ayurveda.calculate_ayurvedic_constitution(
    date='1990-07-04', time='10:12:00',
    latitude=28.6139, longitude=77.209, timezone='Asia/Kolkata',
)
print(reading['composite']['type'], reading['composite']['pitta'])
for factor in reading['factors']:
    print(factor['id'], factor['doshas'], factor['source']['text'], factor['source']['verse'])
```

### PHP SDK
```php
<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$reading = $roxy->ayurveda->calculateAyurvedicConstitution(
    date: '1990-07-04',
    time: '10:12:00',
    latitude: 28.6139,
    longitude: 77.209,
    timezone: 'Asia/Kolkata',
);
echo $reading['composite']['type'], ' ', $reading['composite']['pitta'];
```

### C# SDK
```csharp
using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var reading = await roxy.Ayurveda.Constitution.PostAsync(new()
{
    Date = new Date(1990, 7, 4),
    Time = new Time(10, 12, 0),
    Latitude = 28.6139,
    Longitude = 77.209,
    Timezone = new() { String = "Asia/Kolkata" },
});

Console.WriteLine(reading!.Composite!.Type);   // "pitta"
Console.WriteLine(reading.Composite.Pitta);    // 87
```

### Go SDK
```go
import (
    "context"
    roxyapi "github.com/RoxyAPI/sdk-go"
)

roxy, _ := roxyapi.NewRoxy("YOUR_API_KEY")

body := roxyapi.CalculateAyurvedicConstitutionJSONRequestBody{
    Date:      roxyapi.Ptr("1990-07-04"),
    Time:      roxyapi.Ptr("10:12:00"),
    Latitude:  roxyapi.Ptr(28.6139),
    Longitude: roxyapi.Ptr(77.209),
}

reading, _ := roxy.Ayurveda.CalculateAyurvedicConstitution(context.Background(), nil, body)
```

### MCP
```bash
claude mcp add-json --scope user roxy-ayurveda '{"type":"http","url":"https://roxyapi.com/mcp/ayurveda","headers":{"X-API-Key":"YOUR_KEY"}}'
```

Then in any MCP client: "what does my chart say about my dosha, and which verses is that from?" The agent calls the constitution tool and reads the three factors, the composite and the citation on each. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp).

## Read the response

```json
{
  "frame": { "ayanamsa": "lahiri", "ayanamsaDegrees": 23.72820922463809 },
  "lagnaSign": "leo",
  "moonSign": "scorpio",
  "factors": [
    {
      "id": "lagna-sign",
      "input": "leo",
      "doshas": ["pitta"],
      "weight": 2,
      "source": {
        "text": "Brihat Jataka",
        "chapter": "18",
        "verse": "note to 20, the Satyacharya extract",
        "translation": "N. Chidambaram Iyer",
        "year": 1885,
        "publicDomain": true,
        "note": "..."
      }
    },
    { "id": "moon-sign", "input": "scorpio", "doshas": ["pitta"], "weight": 1, "source": {} },
    {
      "id": "strongest-planet",
      "input": "Mars Sun Moon",
      "doshas": ["vata", "pitta", "kapha"],
      "weight": 2,
      "source": {}
    }
  ],
  "composite": {
    "vata": 7,
    "pitta": 87,
    "kapha": 6,
    "dominant": "pitta",
    "secondary": "vata",
    "type": "pitta",
    "convention": "roxyapi/v1",
    "weighting": {
      "lagnaSign": 2,
      "moonSign": 1,
      "strongestPlanet": 2,
      "strongPlanetThreshold": 0.9,
      "dualTypeMargin": 10
    }
  },
  "strengthRanking": [
    { "graha": "Mars", "totalVirupas": 525.53, "rank": 1, "strong": true },
    { "graha": "Sun", "totalVirupas": 521.16, "rank": 2, "strong": true },
    { "graha": "Moon", "totalVirupas": 511.89, "rank": 3, "strong": true }
  ],
  "planetDoshas": [
    {
      "graha": "Sun",
      "sanskritName": "sūrya",
      "doshas": ["pitta"],
      "dhatu": "bone",
      "dhatuSanskrit": "asthi",
      "doshaSource": {},
      "dhatuSource": {}
    }
  ],
  "summary": "The chart reads pitta, and pitta carries the largest share of it at 87 percent. ...",
  "conventions": { "signDoshaScheme": "satyacharya", "ayanamsa": "lahiri" },
  "meta": { "disclaimer": "..." }
}
```

Three things above are abridged so the shape reads in one screen: the two later `factors` entries and every nested `source` after the first are shown empty where the live call returns the full object, `strengthRanking` is the top three of seven, and `planetDoshas` is one row of seven. Nothing else is trimmed.

| Field | What it is |
|---|---|
| `frame` | The sidereal frame the chart was cast in, with the exact `ayanamsaDegrees` used, so a reading is reproducible |
| `lagnaSign`, `moonSign` | The rising sign and the sign the Moon occupies, as canonical English identifiers |
| `factors` | Exactly three entries, `lagna-sign`, `moon-sign` and `strongest-planet`, each with the `doshas` it contributes, its `weight` and the `source` behind it |
| `composite` | The three shares as whole percentages plus `dominant`, `secondary` and `type`. `convention` names the blend and `weighting` publishes the numbers it used |
| `strengthRanking` | All seven grahas by shadbala with `totalVirupas`, `rank` and a `strong` flag, so the third factor can be shown working |
| `planetDoshas` | The seven graha rows from the classical table, each with its humours, its `dhatu` and `dhatuSanskrit`, and a separate `doshaSource` and `dhatuSource` |
| `summary` | Composed prose, in the requested language |
| `conventions` | Every switch this result was computed with, echoed so it can be reproduced |
| `meta.disclaimer` | The scope sentence, in the requested language. Present on every response from this domain |

Branch on `id`, `type`, `graha` and `conventions`, which never translate. Render `summary`, `guidance`, `gloss`, `english`, `meaning` and `note`, which do.

## The three factors are the point

Most of the web reads a dosha off a quiz. The classical Jyotish texts give something narrower and checkable: a humour for each rising sign, a rule letting that table be read across to the sign the Moon occupies, and a statement that the strongest planet imparts its own humour to the native. That is three factors, and this API scores exactly those three:

```typescript
type Factor = {
  id: 'lagna-sign' | 'moon-sign' | 'strongest-planet';
  input: string;              // the sign, or the strong grahas that tied
  doshas: string[];           // what this factor contributes
  weight: number;
  source: { text: string; chapter: string; verse: string; translation: string | null; year: number | null; publicDomain: boolean; note: string };
};
```

**Two things are deliberately not scored.** The lagna lord and the Sun carry no classical rule that they indicate the humour of the native, so neither is a factor. A shorter cited list beats a longer invented one, and a product that shows the citations can say why its answer is three rows rather than five.

**The blend is ours and says so.** The texts give the factors and never the weighting, so `composite.convention` is `roxyapi/v1` and `composite.weighting` publishes the exact numbers the split came from, inside the same response. Store the response and the reading stays reproducible even after the convention moves on, because the version and its weights travelled with it.

`strengthRanking[].strong` marks every graha within `strongPlanetThreshold` of the leader, which is why `factors[2].input` can name more than one. That is the classical allowance for a blended result rather than a rounding artifact, and it is why the example above returns all three humours from one factor.

## Ship the rest

### The dinacharya day

[`POST /ayurveda/dinacharya`](/api-reference#tag/ayurveda/POST/ayurveda/dinacharya) (`getDinacharyaSchedule`) is sunrise, brahma muhurta, the six dosha periods and the routine for one place on one day.

```bash
curl -X POST https://roxyapi.com/api/v2/ayurveda/dinacharya \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"date":"2026-06-21","latitude":51.5074,"longitude":-0.1278,"timezone":"Europe/London"}'
# => sunrise "2026-06-21T03:43:08.061Z", sunset "2026-06-21T20:21:30.887Z",
#    brahmaMuhurta { start: "2026-06-21T02:07:08.061Z", end: "2026-06-21T02:55:08.061Z",
#                    muhurtaMinutes: 48, muhurtasPerAhoratra: 30 },
#    doshaPeriods[0] { dosha: "kapha", start: "...T03:43:08.061Z", end: "...T09:15:55.669Z",
#                      span: "day", third: 1 },
#    routine[0] { order: 1, id: "waking", sanskritName: "brāhmamuhūrta", timing: "sunrise minus 96 minutes to sunrise minus 48 minutes" }
```

Brahma muhurta is a FIXED window, 96 minutes before sunrise to 48 minutes before it, and `muhurtaMinutes` and `muhurtasPerAhoratra` are returned so the arithmetic can be checked in the response. A calculator that scales the window to the length of the night is following a reading the classical commentary rejects, and the two part company badly away from the equator: at 51 north in June the gap runs to better than half an hour.

`doshaPeriods` and `alternatePeriods` always BOTH come back. Whichever `doshaClock` you sent is in `doshaPeriods`, and the other convention is in `alternatePeriods`, so a product can show one and reconcile against the other without a second call. The sunrise-anchored set carries a `third` of 1, 2 or 3 within its `span`; the clock-hour set does not, because a fixed grid has no thirds to number.

### The ritucharya season

[`POST /ayurveda/ritucharya`](/api-reference#tag/ayurveda/POST/ayurveda/ritucharya) (`getRitucharya`) takes a date and nothing else, and returns the season with its real boundaries.

```bash
curl -X POST https://roxyapi.com/api/v2/ayurveda/ritucharya \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"date":"2026-03-01"}'
# => ritu { id: "vasanta", sanskritName: "vasanta", devanagari: "वसन्त", gloss: "spring",
#           start: "2026-02-18T15:51:27.000Z", end: "2026-04-20T01:39:12.000Z",
#           solarMonths: [{ index: 11, id: "pisces", sanskritName: "Meena" }, { index: 0, id: "aries", sanskritName: "Mesha" }] },
#    ayana { id: "uttarayana" }, phase { id: "adana", tastes: [...] },
#    strength { level: "moderate" }, tasteIncreasing { id: "kashaya", english: "astringent" },
#    doshaCycle[0] { dosha: "kapha", state: "aggravated" },
#    conventions { ritucharyaScheme: "sutrasthana-6", rituZodiac: "sayana", hemisphere: "northern" }
```

`ritu.start` and `ritu.end` are the actual ingress instants, not the first of a month, so a seasonal feature turns over at the same moment an almanac does. `tasteIncreasing` is the taste that GROWS IN NATURE across the season, which the verses state and which is broadly the opposite of the `regimen` items beside it; the field description says so and it is the easiest thing in the domain to render backwards.

`doshaCycle` is nine slots across the year, three per dosha, and each entry carries a `meaning` sentence for its `state` written in terms of position and quality. Where two texts disagree on a slot, the entry carries a `note` naming the other reading rather than quietly picking one.

### The daily reading

[`GET /ayurveda/daily`](/api-reference#tag/ayurveda/GET/ayurveda/daily) (`getDailyAyurvedaReading`) is the day and the season for one place in one GET, under the defaults, cached to the UTC rollover.

```bash
curl "https://roxyapi.com/api/v2/ayurveda/daily?date=2026-06-21&latitude=51.5074&longitude=-0.1278&timezone=Europe/London" \
  -H "X-API-Key: $ROXY_API_KEY"
# => brahmaMuhurta { start, end }, doshaPeriods 6 entries,
#    ritu { id: "varsa", gloss: "the rains", ayana: "dakshinayana", phase: "visarga",
#           strength: "lowest", tasteIncreasing: "amla" },
#    summary "The day sits in varsa, and pitta holds the part of it this reading was taken in."
```

It is a narrower shape than the two POSTs, on purpose: `ritu` is flattened to its identifiers, `brahmaMuhurta` carries the two instants without the arithmetic, and `doshaPeriods` carries no `third`. Use it for a home screen and the POST routes when a screen needs the citations.

### The catalogue

Three GETs, no input, and the whole reference layer.

[`GET /ayurveda/doshas`](/api-reference#tag/ayurveda/GET/ayurveda/doshas) (`listDoshas`) is the three with everything on them, and [`GET /ayurveda/doshas/{id}`](/api-reference#tag/ayurveda/GET/ayurveda/doshas/{id}) (`getDosha`) is one of `vata`, `pitta` or `kapha`.

```bash
curl "https://roxyapi.com/api/v2/ayurveda/doshas/vata" -H "X-API-Key: $ROXY_API_KEY"
# => dosha { id: "vata", sanskritName: "vāta", devanagari: "वात",
#            alsoCalled: ["vāyu", "anila", "māruta", "samīraṇa"],
#            element: "vayu, air", modernElementPair: "air with ether",
#            qualities: ["ruksa, dry", ...], qualityGunas: ["ruksha", "laghu", "khara", "sukshma", "cala"],
#            seats: [...], specialSeat: "the colon", seatsVariant: "...",
#            states: { balanced, accumulating, aggravated, settlesWith, source },
#            subDoshas: 5 entries with seat, moves, function and source }
```

`element` is the SINGLE element the classical verses give, and `modernElementPair` is the pair in general circulation. They travel in separate fields because only one of them has a verse behind it, and a product that prints the pair should print it from the field that says what it is.

[`GET /ayurveda/tastes`](/api-reference#tag/ayurveda/GET/ayurveda/tastes) (`listRasas`) is the six rasas plus the complete eighteen-cell matrix in both directions.

```bash
curl "https://roxyapi.com/api/v2/ayurveda/tastes" -H "X-API-Key: $ROXY_API_KEY"
# => total 6, strengthOrder ["madhura","amla","lavana","tikta","katu","kashaya"],
#    rasas[0] { id: "madhura", textForm: "svādu", english: "sweet", elements: ["ap, water"],
#               decreases: ["vata","pitta"], increases: ["kapha"] },
#    matrix { vata: { decreasedBy: ["madhura","amla","lavana"], increasedBy: ["tikta","katu","kashaya"] }, ... }
```

The ORDER carries a claim: the verse states the six give strength in the order named, and it puts bitter before pungent where most modern lists reverse them. `strengthOrder` is that order as an array so a UI can sort by it without hardcoding it.

[`GET /ayurveda/qualities`](/api-reference#tag/ayurveda/GET/ayurveda/qualities) (`listGunas`) is the twenty gunas as ten opposed pairs.

```bash
curl "https://roxyapi.com/api/v2/ayurveda/qualities" -H "X-API-Key: $ROXY_API_KEY"
# => total 10, rule "Increase of all things comes about through what is alike, and the reverse through what is opposite.",
#    pairs[0] { number: 1,
#               a: { id: "guru", english: "heavy", action: "building up", actionSanskrit: "bṛṃhaṇa", doshas: ["kapha"] },
#               b: { id: "laghu", english: "light", action: "lightening", actionSanskrit: "laṅghana", doshas: ["vata","pitta"] } }
```

One `action` word per quality is what turns this from a glossary into the mechanism the rest of the domain runs on: a dosha IS a set of these (`qualityGunas` on each dosha joins straight to `pairs[].a.id` and `pairs[].b.id`), a taste acts through them, and a season carries them. Pair 8 carries a recorded disagreement between two commentators in its own note, because the choice decides which dosha that pair joins to.

## The conventions are typed, defaulted and echoed

Ayurveda is not one text, and the astrological layer it borrows from is not one school either. Where two authorities disagree, this API takes the disagreement as an input instead of choosing silently. Every switch is optional, has a named default, and comes back in `conventions` on the response, so a reading stored today can be reproduced years from now without knowing what the defaults were on the day it was made.

| Convention | Values | Default | Routes | Tradition and century | What it changes |
|---|---|---|---|---|---|
| `signDoshaScheme` | `satyacharya`, `bphs` | `satyacharya` | constitution | Jyotish. The extract is appended to the Brihat Jataka of Varahamihira, who was born in 505 and died in 587, so sixth century; the Parasara recension it is set against is known only from much later printed editions | Which classical sign table the rising sign and the sign the Moon occupies are read through. The two agree exactly on three signs of twelve, overlap in part on seven, and share no humour at all on Scorpio or Sagittarius, so the choice can change the reading outright |
| `ayanamsa` | `kp-newcomb`, `kp-old`, `lahiri`, `raman`, `custom` | `lahiri` | constitution | Jyotish, modern. Every named frame here is a twentieth century determination | The sidereal frame the chart is cast in. It rotates the whole zodiac, so a graha within about 1.45 degrees of a boundary can change sign when you switch, which moves both sign factors |
| `ritucharyaScheme` | `sutrasthana-6`, `vimana-8` | `sutrasthana-6` | ritucharya, daily | Classical Ayurveda. The Charaka Samhita is credited to Charaka, placed between the second century BCE and the second century CE; the Ashtanga Hridaya is Vagbhata, commonly placed around the sixth century though the dating is not settled | Which six-season division the year is cut into. The alternate is NOT a relabelling: pravrt replaces sisira, five of the six boundaries move, and the two schemes agree on only two spans |
| `rituZodiac` | `sayana`, `nirayana` | `sayana` | ritucharya, daily | Indian calendrical practice, modern. The gap between the two readings is the size of the ayanamsa | Which zodiac the season boundaries are measured in. The tropical reading is what published almanacs use for seasons; the sidereal reading runs about 24 days later, so near a boundary the two answer with different seasons for the same date |
| `hemisphere` | `northern`, `southern` | `northern` | ritucharya, daily | No classical source. Modern almanac practice, stated as an assumption in the response | Which half of the world the season names are stated for. It is NEVER inferred from a latitude, because a silent flip would change the answer without the caller asking. `southern` rotates the six names by three places and the response says what was not rotated with them |
| `doshaClock` | `sunrise-anchored`, `clock-hours` | `sunrise-anchored` | dinacharya, daily | The thirds are classical Ayurveda, from the same Ashtanga Hridaya frame chapter. The clock grid has no classical source at all and is labelled modern in the response | How the six dosha periods are cut. Thirds of the actual day and night at your place, or a fixed grid of six four-hour blocks from six in the morning. The grid is only exact at an equinox near the equator |

Two of these are worth a control in your own UI. **`rituZodiac` is why two seasonal calculators disagree**, and the gap is about 24 days rather than a rounding difference, so echoing `conventions.rituZodiac` beside a season name turns an argument into a comparison. **`signDoshaScheme` can change a constitution outright**, since the two tables share no humour at all on two of the twelve signs.

There is a seventh convention and it is not a request field. `composite.convention` is `roxyapi/v1`: the three factors are cited, the weighting across them is not, so the blend is versioned and publishes its own `weighting` object inside every response rather than hiding in a changelog.

## Every response says what it is for

Every route in this domain returns `meta.disclaimer`, a single string, in the language the request asked for:

```json
{
  "meta": {
    "disclaimer": "For general wellness and cultural interest only. This is not medical advice, and it is unrelated to the diagnosis, cure, mitigation, prevention or treatment of any disease or condition. Consult a qualified professional."
  }
}
```

It is a field rather than a note in these docs because it has to travel with the data. A response gets stored, cached, passed to a model and rendered somewhere none of your own copy reaches, and the scope statement needs to be in the payload when that happens. Render it wherever you render the reading, and pass it through when you feed a response to an LLM.

The scope is also a shape rather than a sentence. No route accepts a health complaint, no field names a substance, and no endpoint returns a recommendation of one. What ships is what the texts compute and cite: a constitution from a chart, a clock from a sunrise, a season from an ingress, and a catalogue with a verse on every row. The full boundary and the reasoning behind it are on the [coverage page](/docs/coverage).

## Reply in the user language

Every route accepts `?lang=`. This domain ships German, Spanish, French, Hindi, Portuguese, Russian and Turkish alongside the English source.

```bash
curl -X POST "https://roxyapi.com/api/v2/ayurveda/ritucharya?lang=de" \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"date":"2026-03-01"}'
```

Machine readable identifiers never translate. Dosha `id` stays `vata`, season `id` stays `vasanta`, taste `id` stays `madhura`, quality `id` stays `guru`, `graha` stays `Sun`, `state` stays `aggravated`, and every value in `conventions` stays canonical English. `sanskritName` and `devanagari` are data and are the same in every language. Composed prose does translate in place: `summary`, `gloss`, `english`, `guidance`, `meaning`, `note` and the `states` sentences. Branch on the identifier, render the prose.

## Gotchas

- **Brahma muhurta is fixed, not proportional.** It is sunrise minus 96 minutes to sunrise minus 48, at every latitude and in every season. If your reference scales it to a fifteenth of the night, it is following the reading the classical commentary rejects, and the two differ by better than half an hour at 51 north in June.
- **96 minutes, not 90.** Several modern pages give the window as an hour and a half. That is a rounding of the definition, not the definition.
- **Both dosha clocks always come back.** `doshaPeriods` is the convention you sent and `alternatePeriods` is the other one. A UI that reads only the first array is correct; one that reads both can show why a fixed timetable disagrees with it.
- **`tasteIncreasing` is what the season BRINGS, not what to favour.** The verses state which taste grows in nature across each season, and the `regimen` items beside it are broadly the opposite. Labelling that field as a recommendation is the easiest mistake in the domain.
- **The season boundary is an instant, and the date is reduced to midday UTC.** On a day carrying a boundary, the half that midday falls in is the answer. Send the neighbouring date to see the other side.
- **`hemisphere` is an input.** It is never inferred from a latitude you sent for the dinacharya, because the two routes answer different questions and no classical text handles the southern case.
- **Rahu and Ketu carry no humour.** The classical verses cover the seven grahas, so `planetDoshas` has seven rows and no eighth is supplied. Material in circulation supplies one; nothing classical does.
- **`composite` is a convention, `factors` is the citation.** Render the three factors and their verses when you have room. The percentages are the part with no verse behind them, and the response says so in `convention` and `weighting`.
- **Pagination is nominal on the catalogue routes.** The collections are three, six and ten rows, so `limit` is capped at the collection size and a value above it returns 400. `offset` is there for shape.
- **Sanskrit identifiers never translate.** `id` fields are stable across every `?lang=`, which is what makes them safe to store, compare and use as a CSS class.
- **Every call bills at a flat 1 request.** REST and Remote MCP are identical, with no per-domain fees.

## Frequently asked questions


### Can a birth chart really show a dosha?
The classical Jyotish texts assign a humour to each graha and to each rising sign, give a rule letting the rising-sign table be read across to the sign the Moon occupies, and state that the strongest planet imparts its humour to the native. This API scores exactly those three factors and returns the chapter and verse behind each. What no primary text states is how to weigh the three against each other, so the blend producing the percentage split is labelled a RoxyAPI convention, versioned, and published with its own weights inside every response.

### Is there a dosha questionnaire endpoint?
No, and there is not one behind a flag either. No route accepts answers about a body or a set of habits, no field names a substance, and no endpoint takes a health complaint. What ships is what is computed from birth data, a date and a place, which is also why a reading here is reproducible: the same inputs give the same answer in five years. The full boundary is on the [coverage page](/docs/coverage).

### When is brahma muhurta today?
It opens 96 minutes before sunrise and closes 48 minutes before it, so it moves with the date and the place. Send a `date`, a `latitude` and a `longitude` to `POST /ayurveda/dinacharya` and the response returns both instants along with sunrise, sunset and the six dosha periods. The window is a fixed offset rather than a share of the night, which is the reading the classical commentary settles on outright.

### Which Ayurvedic season am I in?
Send a date to `POST /ayurveda/ritucharya`. The response resolves the ritu from the real solar ingress instants and returns the season with its exact opening and closing times, the half of the year the sun is in, where each dosha stands in its yearly cycle, and the behaviour items the chapter gives. Boundaries are measured in the tropical zodiac by default, which is what published almanacs use for seasons; the sidereal reading is available as a convention and runs about 24 days later.

### Why does my season differ from another calculator?
Almost always because of `rituZodiac`. The tropical and sidereal readings of the same boundary are about 24 days apart, so near a boundary they name different seasons for one date. Every response echoes which reading it used, so the two answers can be compared instead of argued about. The second candidate is `ritucharyaScheme`, where the alternate division moves five of the six boundaries.

### Is any of this medical advice?
No. Every response carries `meta.disclaimer` in the language the request asked for, and it is the sentence shown above: general wellness and cultural interest only, and nothing to do with any medical question. It is a field rather than a footer so it travels with the payload; render it wherever you render the reading. Anyone with a health question should speak to a qualified professional.

### Which texts is this built from?
The Charaka Samhita and the Ashtanga Hridaya for the doshas, the tastes, the qualities, the daily routine and the seasonal regimen, and the Brihat Jataka for the graha and sign rules the constitution reads. Every value ships with the work, the chapter and the verse it comes from, and with whether the cited translation may be quoted or only referenced. Where two texts disagree, both readings are returned rather than one being chosen quietly. The verification register is on the [methodology](/methodology) page.

### Why do the doshas carry two element fields?
Because only one of them has a verse behind it. `element` is the single element the classical verses name, and `modernElementPair` is the pair in general circulation, which no source consulted carries as a verse. Keeping them apart means a product can print either one and still say where it came from, rather than blending an unsourced claim into a cited one.

## Ready-made starter

There is no Ayurveda only template yet. The flagship [astrology-ai-chatbot](https://github.com/RoxyAPI/astrology-ai-chatbot) template connects every domain over Remote MCP by default, so cloning it gives you a working dosha and dinacharya chatbot with no wiring; browse the catalog at [/starters](/starters). For a custom build, the [Next.js integration guide](/docs/integrations/nextjs) is the fastest path.

## What to build next

- The [Vedic astrology guide](/docs/guides/vedic-astrology) covers the chart the constitution is read from. The same birth data drives both, so one screen can show the kundli and the dosha reading side by side on one key.
- The [localization guide](/docs/guides/localization) covers the `?lang=` contract this domain ships seven locales under, and which fields translate against which ones never do.
- The [caching guide](/docs/guides/caching) covers the split this domain has: a constitution for a given birth moment never changes, and neither does a catalogue row, while the daily reading tracks the date.
- The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) shows tool registration so users can ask "when is brahma muhurta here tomorrow" in natural language.