Quickstart

Go from zero to your first answer from Kaal: create a key, top up your wallet, start a consultation, read the answer and ask a follow-up.

Create an API key

Sign in and open the developer dashboard. Click Create key, give it a name and copy it. The key is shown only once.

Store it in an environment variable on your server:
```
export KAALERA_API_KEY="kal_live_..."
```

Top up your wallet

On the same dashboard, add $100, $250 or $500 to your USD wallet (your first recharge must be at least $100, which activates your keys). Business & API pricing is 10% below standard: starting a consultation costs $9 and each follow-up $6.30. There is no free or test API. Check your balance at any time:

curl {BASE}/v1/balance \
  -H "Authorization: Bearer $KAALERA_API_KEY"

const res = await fetch("{BASE}/v1/balance", {
  headers: { Authorization: `Bearer ${process.env.KAALERA_API_KEY}` },
});
const data = await res.json();
console.log(res.status, data);

import os, requests

res = requests.get(
    "{BASE}/v1/balance",
    headers={"Authorization": f"Bearer {os.environ['KAALERA_API_KEY']}"},
)
print(res.status_code, res.json())

{
  "balance_cents": 4370,
  "balance_usd": "43.70",
  "currency": "usd"
}

Create a consultation

Send the birth details and the first question. Kaalera computes the Kundli and starts Kaal on it.

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())

{
  "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"
  },
  "balance_cents": 9100
}

Save consultation.id. The answer is written in the background.

Poll for the answer

Answers usually take a few minutes. Poll every 10 seconds until status is ready and the last message has role: "kaal".

# Repeat every 10 s until status is "ready" and the last message has role "kaal"
curl {BASE}/v1/consultations/6e241e38-dd8f-428b-ae09-a8d7169335d3 \
  -H "Authorization: Bearer $KAALERA_API_KEY"

const headers = { Authorization: `Bearer ${process.env.KAALERA_API_KEY}` };
const id = "6e241e38-dd8f-428b-ae09-a8d7169335d3";

async function waitForAnswer() {
  while (true) {
    const res = await fetch(`{BASE}/v1/consultations/${id}`, { headers });
    const { consultation } = await res.json();
    if (consultation.status === "failed" || consultation.status === "closed") throw new Error(consultation.status);
    if (consultation.status === "ready") {
      const last = consultation.messages.at(-1);
      if (last?.role === "kaal") return last.content;
    }
    await new Promise((r) => setTimeout(r, 10_000)); // poll every 10 s
  }
}

console.log(await waitForAnswer());

import os, time, requests

headers = {"Authorization": f"Bearer {os.environ['KAALERA_API_KEY']}"}
cid = "6e241e38-dd8f-428b-ae09-a8d7169335d3"

while True:
    c = requests.get(f"{BASE}/v1/consultations/{cid}", headers=headers).json()["consultation"]
    if c["status"] in ("failed", "closed"):
        raise RuntimeError(c["status"])
    if c["status"] == "ready" and c["messages"][-1]["role"] == "kaal":
        print(c["messages"][-1]["content"])
        break
    time.sleep(10)  # poll every 10 s

{
  "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",
    "messages": [
      {
        "id": "619016d2-4cf9-432b-848b-dcd9921a3b00",
        "role": "user",
        "content": "When is a good window for a career change?",
        "created_at": "2026-10-12T02:21:34.792Z"
      },
      {
        "id": "e72af372-ed54-4b5e-919c-a31f24f87f06",
        "role": "kaal",
        "content": "**Namaste Asha ji, I am Kaal, Kaalera's astrologer.** I have studied your Kundli, and here is a short overview before I answer your question.\n\n**Who you are**\n- **Lagna (Ascendant): Capricorn, Moon in Capricorn, Shravana nakshatra.** …",
        "created_at": "2026-10-12T02:22:52.000Z"
      }
    ]
  }
}

The first kaal message contains a short opening reading followed by the answer to the question. content is Markdown.

Ask a follow-up

Ask another question in the same consultation. You can switch the answer language with any question; the new language also becomes the consultation default.

curl -X POST {BASE}/v1/consultations/6e241e38-dd8f-428b-ae09-a8d7169335d3/questions \
  -H "Authorization: Bearer $KAALERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "Is the window after March 2027 better for starting my own business?",
  "language": "Hinglish"
}'

const res = await fetch("{BASE}/v1/consultations/6e241e38-dd8f-428b-ae09-a8d7169335d3/questions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KAALERA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "question": "Is the window after March 2027 better for starting my own business?",
  "language": "Hinglish"
}),
});
const data = await res.json();
console.log(res.status, data);

import os, requests

res = requests.post(
    "{BASE}/v1/consultations/6e241e38-dd8f-428b-ae09-a8d7169335d3/questions",
    headers={"Authorization": f"Bearer {os.environ['KAALERA_API_KEY']}"},
    json={
      "question": "Is the window after March 2027 better for starting my own business?",
      "language": "Hinglish"
    },
)
print(res.status_code, res.json())

{
  "question_id": "52feaba7-c23a-4afb-bf6d-f39ec0b88005",
  "status": "answering",
  "balance_cents": 8470
}

Then poll the consultation again, exactly like step 4.

Call the API from your server only. Never put an API key in browser or mobile app code.

Quickstart

Create an API key

Top up your wallet

Create a consultation

Poll for the answer

Ask a follow-up