Use the astrology API with AI assistants

Chat assistants suit astrology well, but a language model cannot calculate a chart. This guide shows how to let an assistant call the astrology API for the facts, and then talk about them.

Why call an API

Ask a language model for a birth chart and it will often invent one that looks right. The API works out real positions from NASA JPL planetary data, and we test them against NASA JPL Horizons. Each yoga, dosha and match answer states the rule behind it. A yoga is a named planet combination, and a dosha is a chart feature seen as a problem. So the assistant can quote a real result and explain where it came from. Our post on how to build an AI astrologer that gets the chart right shows why chatbots guess, with six checks to run before you trust one.

The API's text comes from fixed rules and a written library, not from a language model. The same birth details always give the same answer, which makes an assistant easier to test.

Pick a few tools

Most assistant platforms let the model call functions you define, often called tools. You can build them from our OpenAPI document or write them by hand. Offer a short list. OpenAI's function calling guide suggests fewer than 20 tools at a time, and the astrology API has 65 endpoints. Start with this short set:

• POST /v1/summary: a plain-language summary of one chart.
• POST /v1/dosha/all: manglik dosha, kaal sarp dosh and pitra dosh, each with a plain answer. Manglik dosha is about where Mars sits in the chart, checked for marriage. Kaal sarp dosh means all seven planets sit on one side of Rahu and Ketu. Those are two points on the Moon's path. Pitra dosh is linked to ancestors.
• POST /v1/matching: a match verdict for two people, with what counts for and against.
• GET /v1/panchang/daily: the day's panchang, rahu kaal and good times for a place. The panchang is the Hindu calendar for a day. Rahu kaal is a daily time that tradition avoids for new starts.
• GET /v1/reading/topics: every reading topic with the question it answers, so the assistant can pick the right topic id. It needs no birth data.
• POST /v1/reading/section/{section_id}: one reading, such as topic:professional-life for career.

Every topic id the reading tool can take, such as topic:professional-life, is listed on the Sections and IDs page.

The chart tools need latitude, longitude and a time zone name, not a city name. So the assistant asks for the birth city, and your server looks up its latitude, longitude and zone name before the call. Send the zone name, such as America/New_York, so daylight saving time is right for that date.

When a user does not know their birth time, have the assistant say so and ask. For matching without birth times, use POST /v1/matching/nakshatra. It needs only each person's birth nakshatra (the star group the Moon was in at birth) and its quarter (pada).

Tell the model the rules

Tools alone are not enough. The model also needs to know when to call them and what to say. Put a few plain rules in the system prompt, the instructions the model reads before each chat. For example:

You help people understand their Vedic birth chart.
Get every chart fact from the tools. Never work out a position yourself.
Before you call a chart tool, ask for the birth date, the local birth time and the birth city.
If the person does not know the birth time, say so. Then use only tools that need no time.
Quote the answer, headline and conclusion fields as the tools return them.
Do not add astrology of your own.
When a result names its rule, say which rule it applied.
Treat every reading as a tendency, never as a promise.

Then test the assistant with John Doe’s chart from the quickstart. If it names a rising sign other than Virgo, it is not using the tool.

Quote these fields

Several responses carry text written to be shown to people. Tell the model to quote them, not to add its own astrology.

• answer in every dosha result: status, headline, meaning and next (what to do).
• conclusion in a match: the verdict, the headline, and the concerns and strengths behind it.
• answer in the topic readings (headline and explain), and in_short in the planet readings, a few short lines.
• rule on yogas and doshas, so the assistant can say which rule it applied. Every rule is in the rulebook.

Example tool

A tool definition, in the JSON Schema format most platforms accept:

{
  "name": "check_doshas",
  "description": "Checks a birth chart for manglik dosha, kaal sarp dosh and pitra dosh. Returns a plain-English answer for each. Ask the user for any birth detail you do not have; never guess one.",
  "parameters": {
    "type": "object",
    "properties": {
      "year": { "type": "integer" },
      "month": { "type": "integer", "description": "1 to 12" },
      "day": { "type": "integer" },
      "hour": { "type": "integer", "description": "0 to 23, local time at the birthplace" },
      "minute": { "type": "integer" },
      "latitude": { "type": "number" },
      "longitude": { "type": "number" },
      "timezone": { "type": "string", "description": "A time zone name, such as America/New_York" }
    },
    "required": ["year", "month", "day", "hour", "minute", "latitude", "longitude", "timezone"]
  }
}

And the handler on your server that runs when the model calls it:

// Runs on your server when the model calls check_doshas.
// The API key stays in an environment variable; the model never sees it.
async function checkDoshas(birth) {
  const res = await fetch("https://apiforastrology.com/api/astrology/v1/dosha/all", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ASTROLOGY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(birth),
  });
  if (!res.ok) {
    return { error: `The astrology API answered ${res.status}` };
  }
  const { doshas } = await res.json();
  // Give the model only the plain answers, so it quotes them instead of inventing its own.
  return {
    manglik: doshas.manglik.answer,
    kaal_sarp: doshas.kaalsarpa.answer,
    pitra: doshas.pitra.answer,
  };
}

Keys and birth data

• Call the API from your server, inside the tool handler. Never put an API key in a prompt, a web page or a mobile app.
• We use birth details only to work out the answer. We do not store request bodies. See security and data handling.
• Your AI provider still gets the conversation, including any birth details the user types. Tell your users, and check your provider's data terms.
• Each key has a per-minute limit. An assistant that makes many calls can hit it, so handle 429 as the errors guide describes.