Create a consultation

Computes the birth chart and asks Kaal the first question. Costs 1 credit.

POST/v1/consultations

Request body

fullNamestringrequired

Full name of the person. Up to 120 characters.

genderstringrequired

One of Male, Female, Other.

dateOfBirthstringrequired

Date of birth, e.g. "2 Sep 1990".

timeOfBirthstringrequired

Local time of birth, e.g. "5:24 PM". The more exact, the better the house placements.

placeOfBirthstringrequired

Place of birth as "City, State, Country", e.g. "Jaipur, Rajasthan, India".

timezonestringrequired

IANA time zone of the birth place, e.g. "Asia/Kolkata".

latitudenumberoptional

Latitude of the birth place, −90 to 90. Recommended. If omitted, the place is geocoded from placeOfBirth.

longitudenumberoptional

Longitude of the birth place, −180 to 180. Recommended together with latitude.

languagestringoptional

Language Kaal answers in. Defaults to English. See Languages.

questionstringrequired

The first question, 2 to 600 characters.

Request

curl -X POST {BASE}/v1/consultations \
  -H "Authorization: Bearer $KAALERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fullName": "Asha Verma",
  "gender": "Female",
  "dateOfBirth": "2 Sep 1990",
  "timeOfBirth": "5:24 PM",
  "placeOfBirth": "Jaipur, Rajasthan, India",
  "timezone": "Asia/Kolkata",
  "latitude": 26.9124,
  "longitude": 75.7873,
  "language": "English",
  "question": "When is a good window for a career change?"
}'

const res = await fetch("{BASE}/v1/consultations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KAALERA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "fullName": "Asha Verma",
  "gender": "Female",
  "dateOfBirth": "2 Sep 1990",
  "timeOfBirth": "5:24 PM",
  "placeOfBirth": "Jaipur, Rajasthan, India",
  "timezone": "Asia/Kolkata",
  "latitude": 26.9124,
  "longitude": 75.7873,
  "language": "English",
  "question": "When is a good window for a career change?"
}),
});
const data = await res.json();
console.log(res.status, data);

import os, requests

res = requests.post(
    "{BASE}/v1/consultations",
    headers={"Authorization": f"Bearer {os.environ['KAALERA_API_KEY']}"},
    json={
      "fullName": "Asha Verma",
      "gender": "Female",
      "dateOfBirth": "2 Sep 1990",
      "timeOfBirth": "5:24 PM",
      "placeOfBirth": "Jaipur, Rajasthan, India",
      "timezone": "Asia/Kolkata",
      "latitude": 26.9124,
      "longitude": 75.7873,
      "language": "English",
      "question": "When is a good window for a career change?"
    },
)
print(res.status_code, res.json())

Response

{
  "consultation": {
    "id": "6e241e38-dd8f-428b-ae09-a8d7169335d3",
    "name": "Asha Verma",
    "language": "English",
    "status": "ready",
    "created_at": "2026-10-12T02:21:34.792Z",
    "expires_at": "2026-10-19T02:21:35.278Z"
  },
  "credits_remaining": 2
}

consultation.idstring

Consultation ID. Use it to poll and to ask follow-ups.

consultation.namestring

The fullName you sent.

consultation.languagestring

Default answer language for this consultation.

consultation.statusstring

Session state, starting or ready. The answer itself arrives later; see Get a consultation.

consultation.created_atstring

ISO 8601 timestamp.

consultation.expires_atstring | null

When the consultation closes (7 days after it starts). After that it is read-only.

credits_remaininginteger

Your credit balance after this request.

Errors

Status	Code	When
400	`invalid_request`	A field is missing or invalid. The message lists each problem.
400	`chart_failed`	The chart could not be computed. Check date, time, place and timezone.
401	`invalid_api_key`	Missing, wrong or revoked API key.
402	`insufficient_credits`	Your balance is 0. Buy credits at /developers.
503	`unavailable`	Kaal could not start. You were not charged; retry later.

{
  "error": {
    "code": "invalid_request",
    "message": "fullName: Required; gender: Required; dateOfBirth: Required; timeOfBirth: Required; placeOfBirth: Required; timezone: Required; question: Required"
  }
}