API Reference

Complete endpoint documentation for Vedika API

REST API v1.0 | Production Endpoints Available

Quick Start

Base URLs

Choose the server closest to your location for optimal latency:

🌏 Asia-Pacific (Mumbai) Recommended for India 
https://api.vedika.io
🌎 North America (US Central) Global Fallback 
https://api.vedika.io

Authentication

All API requests require authentication via API key in the header:

Authorization: Bearer vk_live_your_api_key_here

Get your API key from the Dashboard

Endpoints

Birth Chart Generation

Generate complete Vedic birth chart with planetary positions, houses, and yogas

POST 
POST /api/v1/chart

Request Body:

{
  "birthDetails": {
    "date": "1990-01-15",
    "time": "14:30",
    "timezone": "Asia/Kolkata",
    "location": {
      "city": "Mumbai",
      "country": "India",
      "latitude": 19.0760,
      "longitude": 72.8777
    }
  },
  "options": {
    "divisionalCharts": ["D1", "D9", "D10"],
    "yogaDetection": true,
    "doshaAnalysis": true
  }
}

Response (200 OK):

{
  "success": true,
  "data": {
    "planets": [...],
    "houses": [...],
    "yogas": ["Gaja Kesari Yoga", "Budhaditya Yoga"],
    "doshas": {
      "manglik": false,
      "kaal_sarp": false
    },
    "divisionalCharts": {...}
  },
  "credits_used": 2
}

Astrology Query (AI-Powered)

Ask any astrology question and get AI-powered analysis with 82% better accuracy than generic AI

POST 
POST /api/v1/astrology/query

Request Body:

{
  "question": "What is my career prospects in 2025?",
  "birthDetails": {
    "date": "1990-01-15",
    "time": "14:30",
    "location": "Mumbai, India"
  }
}

Response (200 OK):

{
  "success": true,
  "data": {
    "prediction": "Based on your chart analysis...",
    "confidence": 0.972,
    "confidence_score": 0.972,
    "followUpSuggestions": [...]
  },
  "credits_used": 1
}

Compatibility Analysis

Calculate Ashtakoota matching score and detailed compatibility report

POST 
POST /api/v1/compatibility

Request Body:

{
  "person1": {
    "date": "1990-01-15",
    "time": "14:30",
    "location": "Mumbai, India"
  },
  "person2": {
    "date": "1992-05-20",
    "time": "09:15",
    "location": "Delhi, India"
  }
}

Response (200 OK):

{
  "success": true,
  "data": {
    "totalScore": 28,
    "maxScore": 36,
    "percentage": 77.8,
    "kootaBreakdown": {...},
    "manglikAnalysis": {...},
    "recommendation": "Highly compatible"
  },
  "credits_used": 2
}

Health Check

Verify API availability and server status

GET 
GET /api/v1/health

Response (200 OK):

{
  "status": "healthy",
  "uptime": 1234567,
  "version": "1.0.0"
}

API Information

Get API version and capabilities information

GET 
GET /api/v1/info

Response (200 OK):

{
  "name": "Vedika API",
  "version": "1.0.0",
  "features": ["birth-chart", "ai-query", "compatibility"],
  "models": ["Vedika Pro 1.0", "Vedika Standard 2.1", "Vedika Lite 0.9", "Vedika Express 1.5"]
}

Error Codes

Code Message Description
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
402 Payment Required Insufficient credits
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error (we'll fix it!)

Rate Limits

Starter

1,000

requests/month

50 req/min · 100/day

Professional

10,000

requests/month

200 req/min · 1,000/day

Business

50,000

requests/month

500 req/min · 5,000/day

Enterprise

Unlimited

Custom SLA

1,000 req/min · Unlimited

Endpoint-Specific Limits

Certain resource-intensive endpoints have reduced rate limits relative to your plan's base limit:

Endpoint % of Plan Limit Example (Starter 50/min)
/api/v1/astrology/query 50% 25 req/min
/api/v2/astrology/kundli 60% 30 req/min
/api/v2/astrology/transit 80% 40 req/min
/api/batch 10% 5 req/min
/api/streaming 20% 10 req/min

All other endpoints use 100% of your plan's rate limit. Limits scale with your tier — Professional (200/min base) gets 100 req/min for AI queries, etc.

Frequently Asked Questions

What endpoints are available in the Vedika API?

Vedika API offers 516+ calculations including birth chart analysis, planetary positions, dashas, yogas, doshas, compatibility matching, transit predictions, numerology, panchang, and conversational AI chat. Each endpoint supports multiple calculation systems (Vedic, Western, KP) with responses in 30+ languages.

What is the rate limit for API requests?

Rate limits vary by subscription tier: Starter offers 50 requests/min, Professional provides 200/min, Business gets 500/min, and Enterprise receives 1,000/min. Daily limits also apply (100/day for Starter up to unlimited for Enterprise). AI query endpoints have reduced limits to ensure quality. All plans include burst capacity for handling traffic spikes. Check your current usage in the dashboard.

How do I handle API errors?

Vedika API returns standard HTTP status codes: 200 for success, 400 for bad requests, 401 for authentication errors, 402 for insufficient credits, 429 for rate limits, and 500 for server errors. Error responses include detailed JSON with error codes, messages, and suggested actions. Implement exponential backoff for retries.

What response formats are supported?

All endpoints return JSON by default. We also support XML and CSV formats for specific endpoints via the Accept header. Streaming endpoints use Server-Sent Events (SSE) for real-time responses. Response compression (gzip) is automatically enabled to reduce bandwidth usage.

Are there SDKs available for the API?

Yes! We provide official SDKs for JavaScript/Node.js (npm install @vedika-io/sdk) and Python (pip install vedika-sdk). Both include automatic retry logic, error handling, type definitions, and comprehensive examples. Code examples are available for 18 languages including Java, PHP, Ruby, Go, and C#. You can also use tools like Postman or cURL for direct API testing.