Build a complete birth profile for an AI agent

Turn one birth input into every core chart, Western astrology, Vedic, Human Design, BaZi, and numerology, assembled into a single structured profile your AI agent reads before it answers anything about a person. One key, one fan-out. Cache birth-derived data separately from current readings.

An AI agent that talks about someone's chart needs the chart in front of it first. Ask an LLM for a natal chart from memory and it hallucinates degrees, houses, and dasha dates. The fix is to compute the real profile once from verified data and feed it to the model as grounded context.

This guide builds that profile: the location lookup, the five chart domains under one key, the Vedic and Chinese sub-charts, and keeping calculated values distinct from editorial interpretations. Reuse the interpretations in the UI or write your own reading, and pass the model the fields its question needs.

What you can build

• The context block an AI astrology chatbot reads before every reply (grounding layer, stops hallucinated charts)
• A per-user "profile memory" row for an AI companion, computed once at signup
• A practitioner one-sheet: a client's full cross-domain chart on a single screen
• A RAG document per person for a spiritual-insight product
• Multi-domain dashboards (natal wheel + kundli + numerology card from one payload)

Prerequisites

1. A RoxyAPI key. Get your API key.
2. The person's birth date, time, full name, and city (you geocode the city in Step 1).
3. A backend you control (Next.js route, Vercel function, Cloudflare Worker, Bun server). The client never sees the secret key.
4. A persistent store (Postgres, SQLite, Redis, even a JSON column) to cache the assembled profile. Cache birth-derived results by the complete input and calculation version. Current readings need their own expiry.

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

cargo add roxyapi
cargo add tokio --features macros,rt-multi-thread

The worked code below is TypeScript, the reference implementation. Every operation is also available in the other SDKs. The next section maps the method shape per language.

The shape: one input, five domains, one profile

Every call below takes the same birth data. The lead chart is the natal chart (Western); Vedic is the second domain, then Human Design, BaZi and numerology, with the Vedic and Chinese sub-charts deepening them. One key covers all of them, no per-domain fees.

Call it from any SDK

The same operations exist in the TypeScript, Python, PHP, C#, Go, and Rust SDKs. TypeScript, Python, PHP, Go and Rust name each method after the operationId from the shape table above (camelCase in TypeScript and PHP, snake_case in Python and Rust, PascalCase in Go); C# is path-fluent and mirrors the URL. Here is the canonical call, the natal chart, in each:

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

const { data: natal, error: natalError } = await roxy.astrology.generateNatalChart({
  body: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York' },
});
if (natalError) throw natalError;

from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")

natal = roxy.astrology.generate_natal_chart(
    date="1990-07-15", time="14:30:00",
    latitude=40.7128, longitude=-74.006, timezone="America/New_York")

use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));

$natal = $roxy->astrology->generateNatalChart(
    date: '1990-07-15', time: '14:30:00',
    latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York');

using RoxyApi;
using Microsoft.Kiota.Abstractions;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var natal = await roxy.Astrology.NatalChart.PostAsync(new() {
    Date = new Date(1990, 7, 15), Time = new Time(14, 30, 0),
    Latitude = 40.7128, Longitude = -74.006,
    Timezone = new() { String = "America/New_York" } });

import (
    "context"
    "time"
    roxyapi "github.com/RoxyAPI/sdk-go"
)

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

var tz roxyapi.NatalChartRequest_Timezone
_ = tz.FromNatalChartRequestTimezone1("America/New_York") // IANA string; FromNatalChartRequestTimezone0(-5) for a numeric offset

natal, _ := roxy.Astrology.GenerateNatalChart(context.Background(), nil, roxyapi.NatalChartRequest{
    Date: roxyapi.Date(1990, time.July, 15), Time: "14:30:00",
    Latitude: 40.7128, Longitude: -74.006, Timezone: tz,
})

use roxyapi::{Roxy, types};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let roxy = Roxy::new(std::env::var("ROXY_API_KEY")?)?;
    let birth = types::NatalChartRequest::new(
        "1990-07-15".into(), "14:30:00".into(), 40.7128, -74.006,
        types::NatalChartRequestTimezone::String("America/New_York".into()),
    );
    let natal = roxy.astrology().generate_natal_chart(&Default::default(), &birth).await?;
    println!("Ascendant: {}", natal.ascendant.sign);
    Ok(())
}

The other four charts follow the identical pattern: generateBirthChart, generateBodygraph, generateBaziChart, and generateNumerologyChart (path-fluent roxy.VedicAstrology.BirthChart, roxy.HumanDesign.Bodygraph, roxy.ChineseAstrology.Bazi.Chart, roxy.Numerology.Chart in C#); numerology takes { fullName, year, month, day } instead of the location body, and BaZi needs only date, time and timezone. The full per-method list, with request and response types in every language, ships in each SDK's bundled AGENTS.md and in the Agent Task Cheatsheet, both generated from the same spec so they never drift.

Step 1: Location lookup (run once per person)

Convert the free-text city to coordinates and a timezone with the Location API, then reuse the result in every chart call. The raw contract is one authenticated GET; the SDK wraps the same request.

curl -s "https://roxyapi.com/api/v2/location/search?q=New%20York&limit=1" \
  -H "X-API-Key: $ROXY_API_KEY"
# cities[0] => { latitude: 40.7143, longitude: -74.006, timezone: "America/New_York", utcOffset: -4, ... }

const res = await fetch(
  'https://roxyapi.com/api/v2/location/search?q=New York&limit=1',
  { headers: { 'X-API-Key': process.env.ROXY_API_KEY } },
);
const { cities } = await res.json();
const city = cities[0]; // { latitude, longitude, timezone, utcOffset, ... }

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

const { data: loc, error: locError } = await roxy.location.searchCities({ query: { q: 'New York' } });
if (locError) throw locError;
const city = loc.cities[0];

Save { latitude, longitude, timezone }. The IANA timezone string resolves server-side to the DST-correct offset for the birth date, so a July 1990 New York birth gets EDT automatically.

Step 2: The five core charts (reuse one birth input)

The natal chart, the Vedic kundli, the Human Design bodygraph, the BaZi chart, and the numerology chart are the foundation. Reuse the saved birth input across these calls. Cache the birth-derived fields separately from date-dependent fields such as the numerology personal year. Numerology takes { year, month, day } integers plus the birth-certificate fullName, and an optional targetDate: send the local date of the user so the age, the maturity status and the personal cycles turn over on their own day. The chart endpoints take the location from Step 1. Human Design and BaZi require date, time and timezone; coordinates do not sharpen Human Design planetary positions. Reuse only the fields each endpoint accepts.

const birth = {
  date: '1990-07-15',
  time: '14:30:00',
  latitude: city.latitude,
  longitude: city.longitude,
  timezone: city.timezone,
};

const [natal, kundli, bodygraph, bazi, numerology] = await Promise.all([
  roxy.astrology.generateNatalChart({ body: birth }),
  roxy.vedicAstrology.generateBirthChart({ body: birth }),
  roxy.humanDesign.generateBodygraph({ body: birth }),
  roxy.chineseAstrology.generateBaziChart({ body: birth }),
  roxy.numerology.generateNumerologyChart({
    body: { fullName: 'Emma Charlotte Wright', year: 1990, month: 7, day: 15, targetDate: '2026-10-28' },
  }),
]);

Verified operationIds: generateNatalChart, generateBirthChart, generateBodygraph, generateBaziChart, generateNumerologyChart.

Prefer raw HTTP? Every POST chart is the same shape, an X-API-Key header and a JSON birth body:

curl -s -X POST "https://roxyapi.com/api/v2/astrology/natal-chart" \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York"}'

Swap the path for /vedic-astrology/birth-chart, /human-design/bodygraph or /chinese-astrology/bazi/chart with the same body; /numerology/chart takes {"fullName":"Emma Charlotte Wright","year":1990,"month":7,"day":15}.

Response anchors you will read later:

• Natal (natal.data): ascendant.{ sign, degree }, midheaven.{ sign, degree }, planets[].{ name, sign, degree, house, isRetrograde }, houses[].{ number, sign, degree }, aspects[].{ planet1, planet2, type, orb }.
• Kundli (kundli.data): meta.{Graha}.{ rashi, longitude, nakshatra: { name, pada, lord }, house, awastha, isRetrograde } for Sun through Ketu plus Lagna, twelve sign-keyed house entries, and yogas[].
• Human Design (bodygraph.data): type, strategy, authority, profile, plus centers, channels, gates, and incarnationCross.
• BaZi (bazi.data): pillars[].{ position, id, stem, branch, tenGod, hiddenStems, naYin } for year, month, day and hour, plus dayMaster.{ element, polarity }, fiveElements[].{ element, count, level }, interactions[], zodiacAnimal, and the conventions the chart was built with.
• Numerology (numerology.data): coreNumbers.{ lifePath, expression, soulUrge, personality, birthDay, maturity }, each { number, calculation, type, hasKarmicDebt }, plus additionalInsights, luckyAssociations, summary.

Step 3: Add Vedic depth

For a full profile, layer the Vedic sub-charts on the same birth body. Each is one call, all under the same key.

const [dasha, navamsa, yogas, manglik, kalsarpa, sadhesati, ashtakavarga, shadbala, kp] =
  await Promise.all([
    roxy.vedicAstrology.getCurrentDasha({ body: birth }),
    roxy.vedicAstrology.generateNavamsa({ body: birth }),
    roxy.vedicAstrology.detectYogas({ body: birth }),
    roxy.vedicAstrology.checkManglikDosha({ body: birth }),
    roxy.vedicAstrology.checkKalsarpaDosha({ body: birth }),
    roxy.vedicAstrology.checkSadhesati({ body: birth }),
    roxy.vedicAstrology.calculateAshtakavarga({ body: birth }),
    roxy.vedicAstrology.calculateShadbala({ body: birth }),
    roxy.vedicAstrology.generateKpChart({ body: birth }),
  ]);

Verified operationIds: getCurrentDasha, generateNavamsa, detectYogas, checkManglikDosha, checkKalsarpaDosha, checkSadhesati, calculateAshtakavarga, calculateShadbala, generateKpChart. For the full 120-year timeline instead of just the running period, swap getCurrentDasha for getMajorDashas.

The Jaimini layer

Arudha padas and Chara Karakas complete the classical profile. Both take the same birth object, so they join the same fan-out:

const [arudha, charaKarakas] = await Promise.all([
  roxy.vedicAstrology.calculateArudhaPadas({ body: birth }),
  roxy.vedicAstrology.calculateCharaKarakas({ body: { ...birth, scheme: 'eight' } }),
]);

Verified operationIds: calculateArudhaPadas, calculateCharaKarakas. The avastha readings referenced by the birth chart are served separately by listAvasthas (GET /vedic-astrology/avasthas) and getAvastha.

calculateArudhaPadas returns the twelve Jaimini padas (AL through UL) with the derivation attached. calculateCharaKarakas returns the ranked karaka offices plus atmakaraka and darakaraka at the top level.

What each adds: getCurrentDasha returns the running mahadasha, antardasha, and pratyantardasha lords (the timing layer). generateNavamsa returns the D9 chart. detectYogas returns 48 verdicts, the 12 classical, all 32 Nabhasa and the four wealth and poverty verdicts, each as yogas[].{ name, present, quality, family, evidence }. Each dosha returns { present } plus details when present. calculateShadbala returns per-planet strength in rupas; calculateAshtakavarga returns bindu totals per sign.

Step 3b: Add Chinese metaphysics depth

The BaZi chart from Step 2 has the same relationship to the Chinese layer that the kundli has to the Vedic one: everything else reads off it. Three more calls complete it, and all three are deterministic from immutable birth data, so they cache alongside the rest of the profile.

const [dayMaster, luckPillars, kua] = await Promise.all([
  roxy.chineseAstrology.calculateDayMasterStrength({ body: birth }),
  roxy.chineseAstrology.calculateLuckPillars({ body: { ...birth, gender: 'female' } }),
  roxy.fengShui.calculateKuaNumber({ body: { date: birth.date, gender: 'female' } }),
]);

Verified operationIds: calculateDayMasterStrength, calculateLuckPillars, calculateKuaNumber.

What each adds: calculateDayMasterStrength returns the verdict (strong or weak), a numeric score, the three factors that produced it, and the favorableElements and unfavorableElements every downstream recommendation reads. calculateLuckPillars returns the ten-year cycles with startAge, startYear and endYear, which is the timing layer, the Chinese counterpart of a dasha. calculateKuaNumber is the feng shui entry point: one date plus a formula selector returns the personal number, the east or west group, and all eight compass directions ranked, which is what a placement or direction feature is built on.

Step 4: Assemble one profile in a single server route

Fan out every call behind one route and return a single payload. This combined response includes current dasha, Sade Sati and annual numerology. Fetch current readings fresh or give them an explicit expiry; cache natal results separately if needed.

Use the authenticated application session to select the saved profile. Never trust an arbitrary userId query parameter to authorize access to private birth data. Reuse the parallel calls in Steps 2 and 3 after that authorization check. Return only the data that account is permitted to read.

const profile = {
  natal: natal.data!, kundli: kundli.data!, humanDesign: bodygraph.data!,
  bazi: bazi.data!, numerology: numerology.data!,
  dasha: dasha.data!, navamsa: navamsa.data!, yogas: yogas.data!,
  doshas: { manglik: manglik.data!, kalsarpa: kalsarpa.data!, sadhesati: sadhesati.data! },
  dayMaster: dayMaster.data!, kua: kua.data!,
};
type Profile = typeof profile;

Handle SDK errors before assembling this object. The example above assumes the calls succeeded.

Step 5: Strip to core numbers for the agent

The responses can include editorial interpretation text alongside calculated values. Keep both available: your product can render that text or write its own interpretation. Trim only fields the model does not need for its actual question. The example below selects a compact set of fields for chart questions.

function toAgentContext(p: Profile) {
  const cn = p.numerology.coreNumbers;
  return {
    numerology: {
      lifePath: cn.lifePath.number,
      expression: cn.expression.number,
      soulUrge: cn.soulUrge.number,
      personality: cn.personality.number,
      birthDay: cn.birthDay.number,
      maturity: cn.maturity.number,
    },
    western: {
      ascendant: `${p.natal.ascendant.sign} ${p.natal.ascendant.degree.toFixed(2)}`,
      midheaven: `${p.natal.midheaven.sign} ${p.natal.midheaven.degree.toFixed(2)}`,
      planets: p.natal.planets.map((pl) => ({
        body: pl.name, sign: pl.sign, degree: Number(pl.degree.toFixed(2)),
        house: pl.house, retrograde: pl.isRetrograde,
      })),
    },
    humanDesign: {
      type: p.humanDesign.type,
      strategy: p.humanDesign.strategy,
      authority: p.humanDesign.authority,
      profile: p.humanDesign.profile,
    },
    chinese: {
      dayMaster: `${p.bazi.dayMaster.polarity} ${p.bazi.dayMaster.element}`,
      strength: p.dayMaster.verdict,
      favorableElements: p.dayMaster.favorableElements,
      zodiacAnimal: p.bazi.zodiacAnimal,
      pillars: p.bazi.pillars.map((pl) => ({
        position: pl.position, id: pl.id, tenGod: pl.tenGod.name,
      })),
      elementCounts: Object.fromEntries(p.bazi.fiveElements.map((e) => [e.element, e.count])),
      // Keep this: it is what makes the chart above reproducible later.
      conventions: p.bazi.conventions,
      kua: { number: p.kua.kua, group: p.kua.group },
    },
    vedic: {
      lagna: p.kundli.meta.Lagna.rashi,
      moonNakshatra: `${p.kundli.meta.Moon.nakshatra.name} pada ${p.kundli.meta.Moon.nakshatra.pada}`,
      planets: Object.values(p.kundli.meta).map((g) => ({
        graha: g.graha, rashi: g.rashi,
        nakshatra: g.nakshatra.name, pada: g.nakshatra.pada, house: g.house,
      })),
      currentDasha: {
        maha: p.dasha.mahadasha.planet,
        antar: p.dasha.antardasha.planet,
        pratyantar: p.dasha.pratyantardasha.planet,
      },
      yogasPresent: p.yogas.yogas.filter((y) => y.present).map((y) => y.name),
      doshas: {
        manglik: p.doshas.manglik.present,
        kalsarpa: p.doshas.kalsarpa.present,
        sadhesati: p.doshas.sadhesati.present,
      },
    },
  };
}

That object contains structured chart values and current readings. Persist birth-derived values as profile memory, and refresh current dasha and Sade Sati before treating them as current.

Step 6: Feed it to your LLM as grounded context

Inject the stripped profile into the system prompt. The model now answers from real, verified positions instead of inventing them, and writes in your product's voice.

const context = toAgentContext(profile);

const system = `You are the in-app astrologer for Acme Stars. Warm, specific, never vague.
Answer ONLY from the verified birth profile below. Never invent positions, degrees, or dates; if a question needs data not present here, say so.
Reply in the user's language. Keep domain terms (planet, nakshatra, gate) in their original form. Never mention APIs, tools, or that this profile was precomputed; speak as if you simply know it. End with one actionable insight.

BIRTH PROFILE (verified, core numbers only):
${JSON.stringify(context, null, 2)}`;

// Pass `system` to your model (OpenAI, Anthropic, Gemini, or any provider).

This is the profile-context pattern: reuse birth-derived data and refresh current readings before grounding replies on them. For the live tool-calling variant, where the model fetches charts mid-conversation, the open-source astrology-ai-chatbot template ships a production system prompt (location-first procedure, ambiguous-date disambiguation, multilingual replies, never reveal the tools) worth adapting.

For a chatbot that should also fetch fresh data mid-conversation (today's transits, a compatibility score with another person), keep this profile as the base context and add the per-domain Remote MCP servers so the agent can call verified tools live on top of it.

Optional layers and what is left out

The five charts plus the Vedic and Chinese depth above combine a birth-derived profile with current readings. More layers are available when a product needs them, all on the same key and the same birth body:

• More Western depth. POST /astrology/asteroids, POST /astrology/arabic-lots, and POST /astrology/fixed-stars add natal points and bodies the core chart does not return.
• More Vedic depth. POST /vedic-astrology/divisional-chart for any varga beyond D9 (D10 career, D7 children, and so on), POST /vedic-astrology/upagraha for the subtle calculated points, POST /vedic-astrology/bhava-bala for house strength, POST /vedic-astrology/bhav-chalit for the cusp-based house shifts, and POST /vedic-astrology/dasha/sub/{mahadasha} for sub-period drill-down.
• More Human Design depth. POST /human-design/variables returns the four arrows (determination, environment, perspective, motivation) on the same birth body.
• More Chinese depth. POST /chinese-astrology/bazi/compatibility scores two charts against each other for matchmaking, and POST /feng-shui/eight-mansions expands the Kua number into the full ranked direction map with a reading per sector.
• Mesoamerican day signs. POST /mesoamerican-astrology/mayan/chart returns the Tzolkin day sign and trecena, the Long Count and the Calendar Round, and POST /mesoamerican-astrology/aztec/tonalpohualli the Aztec day sign, both from the birth date alone.
• More numerology. POST /numerology/chaldean returns the Chaldean (Cheiro) compound numbers alongside the Pythagorean chart, POST /numerology/dual sets the two systems side by side for one name, and POST /numerology/bridge returns the bridge numbers between the core numbers.
• Kabbalah. POST /kabbalah/birth-profile returns the Hebrew birth date, the next Hebrew birthday and the birth angels; POST /kabbalah/name-profile reads the name through gematria.
• Ayurveda. POST /ayurveda/constitution returns the dosha constitution (vata, pitta, kapha shares) read from the sidereal chart.
• Lifestyle layer. GET /crystals/birthstone/{month} and GET /crystals/zodiac/{sign} map the birth month and sun sign to stones.

Deliberately left out of the static profile:

• The dynamic layer. Transits, progressions, solar and lunar returns, profections, the BaZi annual forecast, the flying star and affliction overlays, and the forecast timeline change with the calendar, so they are computed live, not cached into the profile. Add them at request time over Remote MCP on top of the cached profile.
• Non-birth domains. Tarot, I Ching, dreams, and angel numbers are not derived from birth data (a tarot draw is random, an angel number is a lookup), so they are not part of a birth profile.
• Biorhythm is birth-date driven but cyclical (it changes every day), so treat it as a daily metric, not a static profile field.

Gotchas

• Numerology takes integers, not a date string. { year, month, day }, not 1990-07-15. The fullName is the birth-certificate name, used for the letter-based numbers (expression, soul urge, personality). targetDate is a date string: today in the zone of the user.
• A few birth endpoints take a different body. /astrology/solar-return takes birthDate, birthTime and returnYear; the biorhythm routes take birthDate; /kabbalah/birth-profile takes date, time and timezone with no coordinates; /mesoamerican-astrology/mayan/chart and /mesoamerican-astrology/aztec/tonalpohualli take date only; /feng-shui/kua takes date and gender. Map the saved birth input per call.
• The Vedic kundli is keyed by sign and by graha. generateBirthChart returns a twelve sign-keyed house map plus a meta object keyed by planet. Read meta.{Graha} for a clean per-planet view; do not expect a flat planets[] array like the Western chart.
• Human Design and BaZi need only date, time, and timezone. Coordinates are optional on both, so they are the two charts that still work when the birth city is unknown. Read type, strategy, authority, and profile from the Human Design response, and pillars, dayMaster and conventions from the BaZi one.
• The BaZi chart is read right to left, and stores its own school settings. pillars[0] is the year and pillars[3] is the hour, while the conventional presentation puts the hour on the left, so reverse the array when you render. Persist conventions with the chart: it is the only thing that lets you reproduce the same pillars later.
• Select context for the question. Keep calculated values distinct from editorial readings. Retain interpretations for the UI or model when useful; omit unnecessary fields to reduce input tokens.
• Separate natal and current caches. Include complete birth inputs, chosen conventions and calculation version in natal cache keys. Current dasha, Sade Sati, annual numerology, the numerology maturity status and the next Hebrew birthday need expiry and refresh.
• One plan, every domain. All the calls above bill at a flat 1 request each, REST and MCP identical. No per-domain fees, no batch endpoints.
• Positions are read directly from the NASA JPL DE440 ephemeris and verified against NASA JPL Horizons. The same Roxy Ephemeris powers the Western, Vedic, Human Design, and KP layers, so every domain agrees on the same sky.

Frequently asked questions

What to build next

• The AI astrology chatbot tutorial wires this profile into a full conversational app over Remote MCP.
• The AI companion with memory tutorial adds vector recall of past readings on top of this same profile.
• The Western astrology, Vedic astrology, Human Design, Chinese astrology, feng shui, and numerology guides cover the rest of the endpoints in each domain.
• The MCP setup connects your agent to live verified tools so it can fetch fresh data on top of the cached profile.