AI Astrology Query API - V1 Endpoint

Overview

Primary AI-powered Vedic and Western astrology endpoint. Ask any astrology question with birth details and receive a detailed, professional analysis powered by Swiss Ephemeris calculations and AI interpretation.

Authentication

All requests require an API key passed via the x-api-key header. Get your key from the Dashboard.

Request — Standard Speed

curl -X POST "https://api.vedika.io/api/v1/astrology/query" \
  -H "Content-Type: application/json" \
  -H "x-api-key: vk_live_YOUR_API_KEY" \
  -d '{
    "question": "What does my birth chart say about my career?",
    "birthDetails": {
      "datetime": "1990-05-15T10:30:00",
      "latitude": 28.6139,
      "longitude": 77.2090,
      "timezone": "+05:30"
    }
  }'

Request — Fast Speed

Add "speed": "fast" for faster responses (~8-12s vs ~19-24s). Uses a higher-capability model at increased per-query cost.

curl -X POST "https://api.vedika.io/api/v1/astrology/query" \
  -H "Content-Type: application/json" \
  -H "x-api-key: vk_live_YOUR_API_KEY" \
  -d '{
    "question": "Analyze my Vimshottari Dasha periods",
    "birthDetails": {
      "datetime": "1990-05-15T10:30:00",
      "latitude": 28.6139,
      "longitude": 77.2090,
      "timezone": "+05:30"
    },
    "speed": "fast"
  }'

Parameters

Parameter	Type	Required	Description
`question`	string	Yes	Your astrology question (1-5000 chars)
`birthDetails`	object	For personal queries	Birth details object (see below). Not required for educational questions.
`birthDetails.datetime`	string	Yes*	ISO 8601 datetime, e.g. `"1990-05-15T10:30:00"`
`birthDetails.latitude`	number	Yes*	Birth location latitude (-90 to 90)
`birthDetails.longitude`	number	Yes*	Birth location longitude (-180 to 180)
`birthDetails.timezone`	string	Recommended	UTC offset, e.g. `"+05:30"`. Auto-inferred from coordinates if omitted.
`speed`	string	No	`"standard"` (default, ~19-24s) or `"fast"` (~8-12s, higher cost). Available on all plans.
`language`	string	No	ISO 639-1 code (e.g. `"hi"`, `"ta"`). Auto-detected if omitted.
`conversationId`	string	No	Include for multi-turn follow-up questions.
`includeRemedies`	boolean	No	Include Vedic remedies in the response.

* Required when birthDetails is provided.

Response

{
  "success": true,
  "response": "Based on your birth chart, your ascendant is Virgo (Kanya Lagna)...",
  "followUpSuggestions": [
    "What about my career prospects?",
    "Tell me about my Vimshottari Dasha periods"
  ],
  "metadata": {
    "model": "Vedika Pro Ultra",
    "processing_time_ms": 8432,
    "engine": "vedika-intelligence",
    "speed": "fast",
    "usage": {
      "input_tokens": 2200,
      "output_tokens": 950,
      "total_tokens": 3150
    },
    "cost": {
      "total_usd": 0.084,
      "currency": "USD"
    },
    "wallet": {
      "balance_before": 54.56,
      "deducted": 0.084,
      "balance_after": 54.476,
      "currency": "USD"
    }
  },
  "birthChart": {
    "ascendant": { "sign": "Virgo", "degree": 15.23 },
    "planets": [ ... ],
    "houses": [ ... ]
  },
  "conversationId": "conv_abc123"
}

Speed Tiers

Speed	Response Time	Typical Cost	Availability
`standard` (default)	~19-24 seconds	~$0.01 per query	All plans
`fast`	~8-12 seconds	~$0.08 per query	All plans

The X-Vedika-Speed response header confirms which speed tier was used.

Error Handling

// 400 — Validation Error
{
  "error": "Validation Error",
  "message": "Invalid input data",
  "code": "VALIDATION_ERROR",
  "details": [{ "field": "question", "message": "Question is required" }]
}

// 402 — Insufficient Balance
{
  "error": "Payment Required",
  "message": "Insufficient wallet balance.",
  "code": "INSUFFICIENT_BALANCE_PRECHECK",
  "wallet": { "required": 0.10, "available": 0.03, "deficit": 0.07 },
  "purchaseUrl": "https://vedika.io/dashboard"
}

Rate Limits

Starter ($12/mo): 1,000 requests/month
Professional ($60/mo): 10,000 requests/month
Business ($120/mo): 50,000 requests/month
Enterprise ($240/mo): 200,000 requests/month

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) are included in every response.

SDKs

JavaScript/Node.js

import { VedikaClient } from '@vedika-io/sdk';

const client = new VedikaClient('vk_live_YOUR_API_KEY');

const result = await client.askQuestion({
  question: 'What does my chart say about career?',
  birthDetails: {
    datetime: '1990-05-15T10:30:00',
    latitude: 28.6139,
    longitude: 77.2090,
    timezone: '+05:30'
  },
  speed: 'fast' // optional
});

Python

from vedika import VedikaClient

client = VedikaClient('vk_live_YOUR_API_KEY')

result = client.ask_question(
    question='What does my chart say about career?',
    birth_details={
        'datetime': '1990-05-15T10:30:00',
        'latitude': 28.6139,
        'longitude': 77.2090,
        'timezone': '+05:30'
    },
    speed='fast'  # optional
)

AI Astrology Query