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.
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 returns the latitude, longitude and IANA timezone on the same key.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package RoxyApi.Sdk

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 -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 }'

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"

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

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'];

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

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)

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

Read the response

{
  "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.

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:

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 (getDinacharyaSchedule) is sunrise, brahma muhurta, the six dosha periods and the routine for one place on one day.

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 (getRitucharya) takes a date and nothing else, and returns the season with its real boundaries.

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 (getDailyAyurvedaReading) is the day and the season for one place in one GET, under the defaults, cached to the UTC rollover.

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 (listDoshas) is the three with everything on them, and GET /ayurveda/doshas/{id} (getDosha) is one of vata, pitta or kapha.

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 (listRasas) is the six rasas plus the complete eighteen-cell matrix in both directions.

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 (listGunas) is the twenty gunas as ten opposed pairs.

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.

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:

{
  "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.

Reply in the user language

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

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

Ready-made starter

There is no Ayurveda only template yet. The flagship 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. For a custom build, the Next.js integration guide is the fastest path.

What to build next

• The Vedic astrology guide 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 covers the ?lang= contract this domain ships seven locales under, and which fields translate against which ones never do.
• The caching guide 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 shows tool registration so users can ask "when is brahma muhurta here tomorrow" in natural language.