PDFs

Four routes return a finished, printable PDF instead of JSON. Each is an existing route with /pdf in front: the same body, a few PDF fields beside it, and application/pdf back. The numbers in a PDF are the numbers the JSON route gives — there is no separate calculation.

PDFs are on every paid plan — Starter, Growth, Scale and Enterprise — and not on Free. A secret key (kj_live_…, kj_test_…) only: publishable keys cannot make PDFs.

The body#

Everything the JSON route takes, plus:

and from options:

• options.language — "en", "hi", or ["en", "hi"] for both side by side (the first language is the left column and the chart labels). Hindi is properly shaped Devanagari.
• options.disclaimer — the closing line of the written parts, exactly as on the report routes: "default", "off", or { "name": "…", "url": "…" } to name the astrologer to consult.
• options.ayanamsa — as everywhere.

curl https://api.kaaljyoti.com/v1/pdf/kundli \
  -H "Authorization: Bearer $KJ_KEY" \
  -H "Content-Type: application/json" \
  -o kundli.pdf \
  -d '{
    "birth": {
      "datetime": "1990-05-14T10:30:00",
      "timezone": "Asia/Kolkata",
      "latitude": 28.6139,
      "longitude": 77.209,
      "place": "New Delhi"
    },
    "name": "Ravi Kumar",
    "template": "modern",
    "vargas": ["d1", "d9"],
    "options": { "language": ["en", "hi"] }
  }'

A match:

POST /v1/pdf/match
{
  "bride": { "datetime": "1994-02-11T06:20:00", "timezone": "Asia/Kolkata", "latitude": 26.8467, "longitude": 80.9462 },
  "groom": { "datetime": "1991-09-03T21:05:00", "timezone": "Asia/Kolkata", "latitude": 19.076, "longitude": 72.8777 },
  "name": "Sita",
  "partner_name": "Ram",
  "options": { "language": "hi" }
}

A varshphal takes the year; a panchang month the place and month:

POST /v1/pdf/varshphal
{ "birth": { … }, "year": 2026, "name": "Ravi Kumar" }

POST /v1/pdf/panchang/month
{ "latitude": 25.3176, "longitude": 82.9739, "timezone": "Asia/Kolkata", "month": "2026-10", "template": "minimal" }

The kundli editions#

A kundli PDF comes in two editions, chosen per request with edition. Both cost the same 1,000 credits and one PDF from the allowance. The cover names the edition — "Basic Horoscope" / "संक्षिप्त जन्मपत्रिका" or "Professional Horoscope" / "विस्तृत जन्मपत्रिका" — and carries only the person's name and city (from name and birth.place; without a name, only the title). The birth date, time, coordinates and zone are on the next page, never on the cover.

*The low end is English or Hindi; the high end is both languages side by side. A PDF never passes 60 pages; the longest, a professional kundli in both languages, runs to about 45.

Every section opens with a short introduction — what it shows and how to read it — and every chart carries a one-line caption, in the PDF's language. The overview is one page for the client: lagna, Moon sign, nakshatra, the mahadasha running now with its level, the chart's overall line, and every life area's level at a glance.

The bhava chalit's house system#

The professional edition's bhava chalit follows options.house_system, which now defaults to placidus: placidus, equal, sripati and kp print that system's sandhi and madhya. whole_sign and porphyry print a Sripati chalit — whole-sign houses have no chalit of their own (the houses are the signs), and Sripati's madhyas are Porphyry's. The readings, the charts and the positions' house numbers stay whole-sign from the lagna whatever you choose.

house_system belongs to this route alone: it is the only place the API reads a house system from options, so the other PDFs and the JSON routes do not take it (sent there, it is a 400 validation_error naming options.house_system).

Sections#

sections picks the sections to print, in any order (the PDF keeps its own order); when it is left out, the edition decides. Use it to leave something out of an edition, or to add one table to a basic kundli:

The cover always prints, and the closing note follows options.disclaimer. The charts page holds two vargas beside the Moon chart. With the vargas section, vargas may list up to 16: the first two go on the charts page, the rest to the divisional charts pages. Without it, more than two is a 400.

POST /v1/pdf/kundli
{
  "birth": { … },
  "name": "Ravi Kumar",
  "edition": "professional",
  "template": "traditional",
  "options": { "language": "hi", "house_system": "sripati" }
}

A basic kundli with the KP tables added:

{ "birth": { … }, "sections": ["details", "charts", "kp_planets", "kp_cusps", "vimshottari", "overview", "life_areas", "yogas"] }

The answer#

A 200 with the PDF itself:

Content-Type: application/pdf
Content-Disposition: attachment; filename="kundli-ravi-kumar.pdf"
X-KJ-Cache: miss
X-KJ-Credits: 1000
X-KJ-Credits-Remaining: 198000

The file is named <kind>-<name>.pdf, or after the date, year or month when there is no name. Nothing is stored: the PDF is the response, and a PDF you want to keep is one you save. An error is the usual JSON

error body, never a PDF.

Your branding#

Set it once on the Branding page: name, logo (PNG, JPEG or SVG, up to 200 KB), address, phone, e-mail, website, an accent colour, a footer line, the default template, and whether the last page says "Powered by Kaal Jyoti" (on by default; you may turn it off). Every PDF your account makes carries it; a change reaches new PDFs within a minute. An SVG logo must be self-contained: no scripts, event handlers or references to other files (it may embed a PNG or JPEG).

Two optional extras, both off until you fill them in:

• Invocation — one line printed at the top of every cover, such as ॥ श्री गणेशाय नमः ॥ or your own words. Text only (English or Hindi), up to 120 characters; no images.
• About us — your own text on a back page after the report: who you are, what you offer, how to reach you. Plain text, up to 1,500 characters; a blank line starts a new paragraph. Left empty, there is no back page.

Templates#

Every template has section headings with small line icons, a colour-coded level badge (favourable, mixed, needs care) wherever a reading is graded, framed charts, and your name and logo in the running header.

Per-request branding is for agencies printing for several astrologers, and is on the Enterprise plan. Send branding with the fields to print — it replaces the account's branding for that PDF, and a field left out is not printed:

"branding": {
  "name": "Pt. Sharma Jyotish Kendra",
  "logo": "data:image/png;base64,iVBORw0KGgo…",
  "phone": "+91 98100 00000",
  "accent": "#8B1E3F",
  "powered_by": false,
  "invocation": "॥ श्री गणेशाय नमः ॥",
  "about": "Pt. Sharma has read charts in Varanasi since 1998.\n\nConsultations by appointment."
}

logo is the file itself, base64 — never a URL. A PDF body may be up to 320 KB to make room for it. An SVG logo follows the same rules as one saved on the Branding page; one that breaks them is refused with 400 validation_error on branding.logo, and nothing is charged. On any other plan, a request that sends branding is refused with 403 plan_required.

Price and allowance#

• A kundli PDF costs 1,000 credits — basic or professional alike. A match, varshphal or monthly panchang PDF costs 500. That is far more than the same content over the JSON routes, on purpose: the rendering is what costs. X-KJ-Credits on the answer says what it cost.
• Each PDF also counts one against the monthly PDF allowance: 50 on Starter, 200 on Growth, 500 on Scale, 2,500 on Enterprise (or as your contract says). It resets on your billing day with the credits, and the Usage page shows it.
• Past the allowance the answer is 402 pdf_quota_exceeded; the credits are not charged, and every other route keeps working.
• A credit pack adds credits, not PDFs: it does not raise the allowance.
• On the Free plan a PDF route answers 403 plan_required.
• PDF routes are heavy: they share the separate 10-requests-a-minute limit.
• A refused request costs nothing — neither credits nor a PDF.

The prices are on Credits per API.

Caching#

The same request by the same account within 24 hours returns the same PDF without drawing it again (X-KJ-Cache: hit), and uses no PDF from the allowance. It still costs its credits, like any cached answer. "The same" is the same body and the same branding: after you change your branding, the next request draws a new PDF.