Avakhada

Endpoint POST https://starsapi.com/api/v3/vedic/natal/avakhada

Returns the Avakhada Chakra — the cultural and classificatory attributes derived from the birth nakshatra and Moon sign. These include namakshar (first syllable of the native’s name), paya (lunar prosperity indicator), and the eight avakhada factors used in Vedic matchmaking and personality profiling: varna, vashya, yoni, gana, nadi, rashi, rashish, and yunja.

Paya is returned in two forms — nakshatra paya (based on Moon’s nakshatra placement in its birth rashi) and rashi paya (based on Moon’s rashi itself). Both are verified against Parashara’s Light. For the birth panchang (tithi, yoga, karana, vaar), call /natal/natal-basics. For inauspicious-period data, call /natal/ghat-chakra.

Authentication

Required. Three methods accepted:

Method	Example
Header (recommended)	`X-Api-Key: am_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer am_live_xxxxxxxxxxxx`
Query	`?api_key=am_live_xxxxxxxxxxxx`

See authentication for security considerations.

Request body

Send a JSON object with Content-Type: application/json. All core fields are required — avakhada attributes are derived from the Moon’s exact sidereal position, which requires precise birth time and place.

Field	Type	Required	Description
`year`	integer	Yes	Birth year, 4-digit (e.g. `1990`).
`month`	integer	Yes	Birth month, `1`–`12`.
`day`	integer	Yes	Day of month, `1`–`31`.
`hour`	integer	Yes	Hour in 24-hour local clock time, `0`–`23`.
`minute`	integer	Yes	Minute, `0`–`59`.
`second`	integer	No	Second, `0`–`59`. Default `0`.
`latitude`	number	Yes	Signed decimal degrees, −90…90. Positive = North (e.g. `28.6139`).
`longitude`	number	Yes	Signed decimal degrees, −180…180. Positive = East (e.g. `77.2090`).
`timezone`	string	Yes	IANA timezone identifier (e.g. `Asia/Kolkata`). DST is resolved automatically.
`name`	string	No	Native’s name. Not returned by this endpoint; use `/vedic/birth-details` to retrieve it.
`place`	string	No	Birth place label. Not returned by this endpoint; use `/vedic/birth-details` to retrieve it.
`ayanamsa`	string	No	Sidereal mode. Default `lahiri`. Full list of 45+ ayanamsas →

Use the local clock time of birth. Pass the wall-clock time as recorded on the birth certificate together with the IANA timezone of the birth place — the backend converts to UTC internally. Do not pre-convert to UTC yourself.

Response shape

The response is grouped into three top-level sections under data: namakshar, paya, and avakhada. Birth input is not echoed back — call /vedic/birth-details separately for that.

namakshar

The auspicious first syllable of the native’s name, derived from the birth nakshatra and pada.

Field	Type	Description
`syllable`	string	Recommended first syllable for the native’s name based on the specific pada.
`all_syllables`	string[]	All four syllables for the birth nakshatra (one per pada).
`nakshatra`	string	Birth nakshatra name.
`nakshatra_pada`	integer	Pada (quarter), `1`–`4`.

paya

Lunar prosperity indicator — classifies the Moon’s placement as Gold, Silver, Copper, or Iron. Returned in two forms for completeness.

Field	Type	Description
paya.nakshatra_paya — based on which rashi the birth nakshatra falls in
`paya`	string	Paya type: `Gold`, `Silver`, `Copper`, or `Iron`.
`paya_hindi`	string	Hindi name (e.g. `Tamra` for Copper).
`quality`	string	General quality: `Excellent`, `Good`, `Average`, or `Poor`.
`description`	string	Brief meaning.
paya.rashi_paya — based on the Moon’s rashi directly
`paya`	string	Same four possible values.
`paya_hindi`	string	Hindi name.
`quality`	string	General quality.
`description`	string	Brief meaning.

avakhada

The eight classical attributes from the Avakhada Chakra, used in matchmaking (Ashtakoot) and personality profiling.

Field	Type	Description
avakhada.varna — spiritual temperament (1–4)
`varna`	string	`Brahmin`, `Kshatriya`, `Vaishya`, or `Shudra`.
`rank`	integer	Numeric rank (1–4).
`description`	string	Brief meaning.
avakhada.vashya — mutual attraction / dominance group
`vashya`	string	Hindi category name (e.g. `Jalchar`).
`vashya_en`	string	English translation (e.g. `Aquatic`).
`description`	string	Brief meaning.
avakhada.yoni — sexual / instinctive compatibility
`yoni`	string	Hindi animal name (e.g. `Gau`).
`animal`	string	English animal name (e.g. `Cow`).
`gender`	string	`Male` or `Female`.
avakhada.gana — temperament class
`gana`	string	`Deva`, `Manushya`, or `Rakshasa`.
`gana_en`	string	English: `Divine`, `Human`, or `Demon`.
`description`	string	Brief meaning.
avakhada.nadi — physiological / health type
`nadi`	string	`Aadi` (Vata), `Madhya` (Pitta), or `Antya` (Kapha).
`nadi_en`	string	Ayurvedic dosha name.
`description`	string	Brief meaning.
avakhada.rashi — Moon sign
`rashi`	string	Hindi sign name (e.g. `Meena`).
`rashi_en`	string	English sign name (e.g. `Pisces`).
`rashi_lord`	string	Ruling planet.
`rashi_number`	integer	Sign number (1–12).
avakhada.rashish — rashi lord details
`lord`	string	Ruling planet in English.
`lord_hindi`	string	Ruling planet in Hindi (e.g. `Brihaspati`).
avakhada.yunja — nakshatra group (trine classification)
`yunja`	string	`Aadi` (First), `Madhya` (Middle), or `Antya` (Last).
`yunja_en`	string	English translation.
`nakshatra_range`	string	Which nakshatra numbers fall in this group (e.g. `19-27`).

Field	Type	Description
`meta.endpoint`	string	Echo of the called endpoint path.
`meta.version`	string	API version (currently `3.0`).
`meta.response_time_ms`	integer	Server-side response time in milliseconds.
`meta.timestamp`	string (ISO 8601)	Time the response was served.
`meta.credits_remaining`	integer	API credits remaining on your plan.
`meta.request_id`	string	Unique request identifier — include in support tickets.
`meta.ayanamsa.name`	string	Sidereal mode applied.
`meta.ayanamsa.value`	number	Ayanamsa offset in decimal degrees.
`meta.ayanamsa.value_dms`	string	Same in D°M′S″ format.

Use cases

Baby naming — use namakshar.syllable to suggest auspicious first syllables based on the birth nakshatra and pada.
Matchmaking — the eight avakhada attributes (varna, vashya, yoni, gana, nadi, rashi, rashish, yunja) are the inputs for Ashtakoot gun milan scoring.
Kundli profile cards — display paya, varna, gana, nadi, and yoni as quick personality indicators alongside the birth chart.
Health profiling — the nadi field maps directly to Ayurvedic dosha (Vata/Pitta/Kapha) for health-related features.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	A required birth field is absent.
400	`INVALID_DATE`	Invalid calendar date.
400	`INVALID_TIME`	Hour/minute/second out of range.
400	`INVALID_TIMEZONE`	Numeric or non-IANA timezone.
400	`INVALID_COORDINATE`	`latitude` / `longitude` out of range.
401	`AUTH_MISSING_KEY`	No API key in request.
401	`AUTH_INVALID_KEY`	Key format invalid or not found.
401	`AUTH_REVOKED_KEY`	Key has been revoked.
403	`AUTH_ORIGIN_DENIED`	Request from non-whitelisted origin.
405	`METHOD_NOT_ALLOWED`	Non-POST request.
429	`RATE_LIMIT_EXCEEDED`	Plan quota exceeded.
500	`CALCULATION_ERROR`	Ephemeris calculation failed.

Error response format

{
  "success": false,
  "error": {
    "code": "INVALID_TIMEZONE",
    "message": "Unrecognised timezone: 'Asia/Calcutta_'. Use a valid IANA identifier such as 'Asia/Kolkata'."
  }
}

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/vedic/natal/avakhada" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/vedic/natal/avakhada',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      year: 1990,
      month: 5,
      day: 20,
      hour: 14,
      minute: 30,
      second: 0,
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 'Asia/Kolkata'
    })
  }
);
const result = await response.json();

if (result.success) {
  console.log(result.data);
}

import requests
import os

response = requests.post(
    'https://starsapi.com/api/v3/vedic/natal/avakhada',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'year': 1990,
        'month': 5,
        'day': 20,
        'hour': 14,
        'minute': 30,
        'second': 0,
        'latitude': 28.6139,
        'longitude': 77.209,
        'timezone': 'Asia/Kolkata'
    }
)
result = response.json()

if result['success']:
    print(result['data'])

<?php
$payload = [
    'year' => 1990,
    'month' => 5,
    'day' => 20,
    'hour' => 14,
    'minute' => 30,
    'second' => 0,
    'latitude' => 28.6139,
    'longitude' => 77.209,
    'timezone' => 'Asia/Kolkata',
];

$ch = curl_init('https://starsapi.com/api/v3/vedic/natal/avakhada');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . getenv('STARSAPI_KEY'),
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    print_r($data['data']);
}

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Map<String, dynamic>> getAscendant() async {
  final response = await http.post(
    Uri.parse('https://starsapi.com/api/v3/vedic/natal/avakhada'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'year': 1990,
      'month': 5,
      'day': 20,
      'hour': 14,
      'minute': 30,
      'second': 0,
      'latitude': 28.6139,
      'longitude': 77.209,
      'timezone': 'Asia/Kolkata',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/vedic/natal/avakhada"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata"
        }
        """.data(using: .utf8)

    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONSerialization.jsonObject(with: data) as! [String: Any]
}

import okhttp3.*
import org.json.JSONObject

val client = OkHttpClient()
val JSON = "application/json; charset=utf-8".toMediaType()

fun getAscendant(callback: (JSONObject) -> Unit) {
    val payload = """
    {
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/vedic/natal/avakhada")
        .addHeader("X-Api-Key", "YOUR_API_KEY")
        .post(payload.toRequestBody(JSON))
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            callback(JSONObject(response.body!!.string()))
        }
        override fun onFailure(call: Call, e: java.io.IOException) {
            e.printStackTrace()
        }
    })
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload, _ := json.Marshal(map[string]interface{}{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/vedic/natal/avakhada",
        bytes.NewBuffer(payload))
    req.Header.Set("X-Api-Key", os.Getenv("STARSAPI_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["data"])
}

require 'net/http'
require 'json'

uri = URI('https://starsapi.com/api/v3/vedic/natal/avakhada')
payload = {
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata'
}

req = Net::HTTP::Post.new(uri)
req['X-Api-Key'] = ENV['STARSAPI_KEY']
req['Content-Type'] = 'application/json'
req.body = payload.to_json

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
res = http.request(req)

data = JSON.parse(res.body)
puts data['data'] if data['success']

200 RESPONSE

{
  "status": 200,
  "success": true,
  "data": {
    "namakshar": {
      "syllable": "Tha",
      "all_syllables": ["Du", "Tha", "Jha", "Da"],
      "nakshatra": "Uttara Bhadrapada",
      "nakshatra_pada": 2
    },
    "paya": {
      "nakshatra_paya": {
        "paya": "Copper",
        "paya_hindi": "Tamra",
        "quality": "Average",
        "description": "Moderate"
      },
      "rashi_paya": {
        "paya": "Copper",
        "paya_hindi": "Tamra",
        "quality": "Average",
        "description": "Moderate"
      }
    },
    "avakhada": {
      "varna": {
        "varna": "Kshatriya",
        "rank": 3,
        "description": "Warrior, protector"
      },
      "vashya": {
        "vashya": "Jalchar",
        "vashya_en": "Aquatic",
        "description": "Water creatures"
      },
      "yoni": {
        "yoni": "Gau",
        "animal": "Cow",
        "gender": "Female"
      },
      "gana": {
        "gana": "Manushya",
        "gana_en": "Human",
        "description": "Balanced nature, practical, worldly"
      },
      "nadi": {
        "nadi": "Madhya",
        "nadi_en": "Pitta",
        "description": "Fire element, Pitta dosha"
      },
      "rashi": {
        "rashi": "Meena",
        "rashi_en": "Pisces",
        "rashi_lord": "Jupiter",
        "rashi_number": 12
      },
      "rashish": {
        "lord": "Jupiter",
        "lord_hindi": "Brihaspati"
      },
      "yunja": {
        "yunja": "Antya",
        "yunja_en": "Last",
        "nakshatra_range": "19-27"
      }
    }
  },
  "meta": {
    "endpoint": "/api/v3/vedic/natal/avakhada",
    "version": "3.0",
    "response_time_ms": 56,
    "timestamp": "2026-06-09T05:58:26+05:30",
    "credits_remaining": 198605,
    "request_id": "778cfcd31883aa30",
    "ayanamsa": {
      "name": "Lahiri",
      "value": 23.725957,
      "value_dms": "23°43'33\""
    }
  }
}