How do I give an AI agent astrology capabilities?

Expose the Vedika API as tools your agent can call. Two routes work: define function-calling schemas that wrap endpoints like POST /api/v1/astrology/query and the /v2/astrology/* computation routes, or connect the public MCP server (npx @vedika-io/mcp-server) which registers 21 ready-made tools an MCP-compatible client can call directly.

What is the difference between the query endpoint and the V2 computation endpoints?

POST /api/v1/astrology/query takes a natural-language question plus birth details and returns a written interpretation, so it suits a conversational agent. The /v2/astrology/* routes return structured data — planetary positions, houses, dashas, yogas — which is better when your agent needs raw values to reason over or render.

Do I need an API key for every call?

Production calls use an x-api-key: vk_live_* header tied to your wallet balance. For prototyping an agent you can hit the free sandbox at vedika.io/sandbox with no key, then swap the base path to api.vedika.io and add the header when you go live.

How are astrological claims kept accurate?

Every chart value is computed by the XALEN Ephemeris, an open-source engine validated against JPL DE440 and swetest, and every interpretive claim is attributable to classical texts used in formal Jyotish, KP, and Western training such as BPHS, Phaladeepika, and Ptolemy's Tetrabiblos. The agent receives sourced statements rather than invented ones.

Giving an AI agent astrology tools via an API

To give an AI agent astrology capabilities, you expose the Vedika API as tools the agent can call. There are two practical routes: write function-calling schemas that wrap endpoints such as POST /api/v1/astrology/query and the structured /v2/astrology/* computation routes, or connect the public Model Context Protocol (MCP) server with npx @vedika-io/mcp-server, which registers 21 pre-built tools any MCP-compatible client can invoke. Both approaches turn a single birth time into charts, dashas, yogas, and sourced interpretations your agent can reason over.

Why an agent needs a dedicated astrology tool

An LLM on its own cannot compute a chart. Planetary longitudes depend on ephemeris data, sidereal versus tropical conventions, ayanamsha selection, house-system math, and dasha period arithmetic — none of which a language model reliably produces from memory. Ask a function-calling model for a Moon position and it will hallucinate a plausible-looking degree. The fix is the same pattern you already use for weather, search, or code execution: hand the model a tool, let it call out for ground truth, and keep the model's job to phrasing and reasoning.

Vedika is built for exactly this hand-off. It exposes 700+ API operations across 25 domains (704 enumerated as of June 2026), spanning three systems in one API — Vedic (sidereal), Western (tropical), and KP — plus Jaimini, Tajaka, Lal Kitab, and numerology. The numbers your agent receives come from the XALEN Ephemeris, Vedika's own open-source engine (Apache-2.0; published to crates.io, PyPI, and npm). It has roughly 2,200 tests and has been validated against JPL DE440 and swetest with zero charts deviating beyond 0.1 degrees across a five-million-chart test run. That is astronomical precision for the positional layer; interpretation is a separate, sourced concern covered below.

Route one: function-calling tool schemas

If you are building on a function-calling model, the cleanest design is two tools: one for natural-language questions and one for structured computation. Keep the schemas narrow so the model knows exactly when to reach for each.

The conversational tool

POST /api/v1/astrology/query accepts a question plus a birthDetails object (datetime, latitude, longitude, timezone) and returns a written interpretation. An optional speed: "fast" flag trades a little depth for lower latency, which is useful inside an interactive agent loop. Here is the raw call your tool wrapper will make:

curl -X POST https://api.vedika.io/api/v1/astrology/query \
  -H "x-api-key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What does my chart say about career direction?",
    "birthDetails": {
      "datetime": "1990-08-15T14:30:00",
      "latitude": 18.5204,
      "longitude": 73.8567,
      "timezone": "Asia/Kolkata"
    },
    "speed": "fast"
  }'

Declaring it to the model

A function-calling schema describes the tool so the model can decide when to call it and how to fill the arguments. The shape below works with any function-calling model — pass it in your client's tools array and route the resulting tool call to the cURL above.

const astrologyQueryTool = {
  name: "astrology_query",
  description:
    "Answer an astrology question for a person given their birth details. " +
    "Use for interpretation, predictions, and chart-based advice.",
  parameters: {
    type: "object",
    properties: {
      question: { type: "string", description: "The user's astrology question" },
      birthDetails: {
        type: "object",
        properties: {
          datetime: { type: "string", description: "ISO local birth datetime" },
          latitude: { type: "number" },
          longitude: { type: "number" },
          timezone: { type: "string", description: "IANA tz, e.g. Asia/Kolkata" }
        },
        required: ["datetime", "latitude", "longitude", "timezone"]
      },
      speed: { type: "string", enum: ["fast"], description: "Optional low-latency mode" }
    },
    required: ["question", "birthDetails"]
  }
};

// When the model emits a call to astrology_query, execute it:
async function runAstrologyQuery(args) {
  const res = await fetch("https://api.vedika.io/api/v1/astrology/query", {
    method: "POST",
    headers: {
      "x-api-key": process.env.VEDIKA_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(args)
  });
  return res.json();
}

The structured-data tool

When your agent needs raw values to reason over or render — a planet table, the current dasha, a list of detected yogas — point a second tool at the /v2/astrology/* routes. These take flat datetime, latitude, longitude, and timezone fields and return structured JSON rather than prose. This separation matters: it lets the model fetch facts and then compose its own explanation, which is easier to validate and to display in a UI.

import os, requests

BASE = "https://api.vedika.io"
HEADERS = {"x-api-key": os.environ["VEDIKA_API_KEY"]}

def get_chart(datetime_str, lat, lon, tz):
    """Structured chart data the agent can reason over."""
    resp = requests.get(
        f"{BASE}/v2/astrology/chart",
        params={
            "datetime": datetime_str,
            "latitude": lat,
            "longitude": lon,
            "timezone": tz,
        },
        headers=HEADERS,
        timeout=20,
    )
    resp.raise_for_status()
    return resp.json()  # planets, houses, ascendant, yogas, etc.

Route two: the MCP server

If your client speaks the Model Context Protocol, you can skip writing schemas entirely. Vedika publishes the first public astrology MCP server, and an MCP-compatible client or IDE can register it with one command:

npx @vedika-io/mcp-server

This exposes 36 tools — chart computation, dasha timelines, transit lookups, compatibility, panchang, and more — already described with names, parameters, and return types. Your LLM agent discovers them at connect time and calls them by name, no glue code on your side. For a developer prototyping an astrology assistant, this is the fastest path from idea to a working tool-using agent. Set VEDIKA_API_KEY in the server's environment for live calls, or run against the sandbox while you iterate.

Streaming answers into a chat agent

Conversational agents feel better when tokens arrive incrementally. The /api/v1/astrology/query/stream endpoint emits Server-Sent Events, so you can forward partial text to your UI as the interpretation is generated rather than blocking on the full payload. Wire it as a streaming tool and pipe the SSE chunks straight into your agent's output channel.

curl -N -X POST https://api.vedika.io/api/v1/astrology/query/stream \
  -H "x-api-key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Summarize my current dasha period.",
    "birthDetails": {
      "datetime": "1990-08-15T14:30:00",
      "latitude": 18.5204,
      "longitude": 73.8567,
      "timezone": "Asia/Kolkata"
    }
  }'

Keeping the agent honest: grounding and citations

The reason a tool beats letting the model freestyle is not only the math — it is provenance. Vedika's interpretive layer follows a strict sourcing rule: every astrological claim must trace to classical texts that real astrologers train from, such as Brihat Parashara Hora Shastra, Phaladeepika, Saravali, Jataka Parijata, the Jaimini Sutras, Krishnamurti's KP Readers, and Ptolemy's Tetrabiblos. Responses carry attributions rather than blog-style paraphrase, which means your agent can show its work and you can defend an answer to a domain expert.

For an agent designer, this changes the failure mode. Instead of a confident, unverifiable sentence, the agent surfaces a computed value plus a sourced interpretation. If you build a verification step into your loop — comparing the model's phrasing against the tool's returned facts — the structured endpoints give you exactly the ground truth to check against.

Honest comparison with other astrology APIs

Several established providers cover the basics well. Prokerala (around $19) has broad endpoint coverage and is widely used; AstrologyAPI.com (around $29) offers a large catalog of Vedic and Western calls; RoxyAPI (around $39) is a solid choice for clean positional data. If your agent only needs a natal chart and a daily panchang, any of them will serve.

Where Vedika differs for agent builders specifically:

An MCP server out of the box — tool discovery with no schema authoring.
A natural-language query endpoint that returns sourced interpretation, not just numbers, so a conversational agent has less to assemble.
Three systems in one key — Vedic, Western, and KP — instead of stitching together separate vendors.
An open-source ephemeris you can audit, run locally, or pin a version of.
30 languages (14 Indic) for multilingual agents.

Pricing and getting started

You can build and test the entire tool integration for free against the sandbox before spending anything. Production runs on a wallet model: plans are Starter $12/mo, Professional $60, Business $120 (which adds the fast path and voice), and Enterprise $240, with per-query cost in the $0.01–$0.05 range depending on the call. See the pricing page for the current breakdown and the API docs for full endpoint references.

Key facts

Conversational tool endpoint: POST /api/v1/astrology/query; streaming variant /api/v1/astrology/query/stream (SSE).
Structured computation: GET /v2/astrology/* with flat datetime, latitude, longitude, timezone.
Auth header: x-api-key: vk_live_*; base URL https://api.vedika.io.
Public MCP server: npx @vedika-io/mcp-server exposes 36 tools to an MCP-compatible client.
700+ operations across 25 domains; Vedic, Western, and KP in one API; 30 languages.
Chart math from the open-source XALEN Ephemeris, validated against JPL DE440 and swetest.
Interpretations attributable to classical texts (BPHS, Phaladeepika, Tetrabiblos, and others).

Bringing it all together

Giving an AI agent astrology tools is a standard tool-use problem with one twist: correctness depends on real ephemeris computation and real source attribution, not on what the model remembers. Wrap the query and /v2 endpoints as function-calling tools, or connect the MCP server and let your client discover them, then let the model do what it is good at — asking the right question and explaining the sourced answer. Start in the free sandbox, and when the loop behaves the way you want, switch the base path to api.vedika.io and add your live key.