Reports API - 21 finished PDF reports under your brand
You send a birth date and get a finished document back. Not JSON you have to lay out yourself, the PDF itself: paginated, carrying your logo, your report title and no mention of us anywhere inside it.
Twenty-one of those are live. With the dispatcher, the export history and five AI narratives that is 28 paths under /v1/reports/*.
The catalogue
Section titled “The catalogue”Every row has a finished sample. It is not a mock-up: the file was generated by the same call printed in that endpoint’s reference page, and it is re-rendered whenever the templates change.
The page count is the one that sample produced, measured 2026-09-21 (2026-11-07 for BaZi, numerology, kundli matching and Chinese year). It moves with the chart: more aspects means more rows, and relocation adds two or three pages per city (4 pages for one city, 13 for five).
| Endpoint | What is inside | Pages | Credits | Sample |
|---|---|---|---|---|
/v1/reports/natal | Big three, planets, houses, aspects | 3 | 5000 | |
/v1/reports/synastry | Cross-aspects between two charts, element balance | 2 | 5000 | |
/v1/reports/transit-yearly | Transit forecast for a chosen year | 5 | 5000 | |
/v1/reports/relocation | Source chart, up to 5 cities, planets that changed house, nearby lines, 19 life areas | 6 | 5000 | |
/v1/reports/vedic-kundli | Lagna and nakshatra, sidereal positions, Vimshottari mahadashas | 2 | 5000 | |
/v1/reports/lal-kitab | Kismat, teva, detected rinas, upayas | 2 | 5000 | |
/v1/reports/gemstone | Stone recommendations with mantras, stones to avoid, graha condition | 7 | 5000 | |
/v1/reports/human-design | Key parameters, centres, channels | 2 | 5000 | |
/v1/reports/muhurta | Ranked auspicious days for one activity | 4 | 5000 | |
/v1/reports/love | Key points of love, big three, aspects | 2 | 5000 | |
/v1/reports/career | Key career points, personality context, aspects | 2 | 5000 | |
/v1/reports/money | Key financial points, houses, aspects | 3 | 5000 | |
/v1/reports/business | Key business points, houses, aspects | 2 | 5000 | |
/v1/reports/child | Key character traits, big three, planets | 2 | 5000 | |
/v1/reports/stellaforge | One-page chart poster: planets, balance, key aspects | 1 | 5000 | |
/v1/reports/tarot | Spread description and the cards | 2 | 100 | |
/v1/reports/vastu | The floor plan with the mandala, score, Vastu findings with sources and remedies | 2 | 5000 | |
/v1/reports/bazi | Four pillars with ten gods and hidden stems, day master, five elements, strength, symbolic stars, interactions, luck pillars | 4 | 5000 | |
/v1/reports/numerology | Six core numbers with their meaning, Balance number, pinnacles and challenges with ages, personal year | 3 | 5000 | |
/v1/reports/kundli-matching | Guna Milan out of 36, Porutham out of 10, Mangal, Nadi and Bhakoot dosha with the rules that cancel them, navamsa, the couple’s dashas side by side | 4 | 5000 | |
/v1/reports/chinese-year | Your animal, the year’s pillar and how it stands to your sign, allies, the twelve solar months | 3 | 5000 |
Tarot costs fifty times less: one page of a spread with no astronomical computation behind it.
Depth: standard or extended
Section titled “Depth: standard or extended”/v1/reports/natal (and /v1/reports/generate with report_type: "natal") takes depth. standard is the document above, 5000 credits. extended is 10000 credits and adds the chart wheel and a chapter for each of Sun to Pluto, Chiron and the Ascendant in its sign: twelve chapters, each two to four pages of edited prose (sample PDF, 13 pages) from the same texts /v1/natal-texts serves. Nothing is generated at request time, so the same chart gives the same document.
The chapters exist in 20 languages, the site’s own; depth: "extended" with any other language is refused with 400 rather than filled from another language. The other report types have one depth for now: their long chapters are not written yet.
One path instead of sixteen
Section titled “One path instead of sixteen”POST /v1/reports/generate takes a report_type field and does exactly what the dedicated path does. Twelve types: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.
For an SDK that is one method instead of twelve, for MCP one tool instead of twelve. The price is identical: a dispatched call is billed exactly as the direct path.
PDF, HTML or Markdown
Section titled “PDF, HTML or Markdown”Every report type, the dispatcher included, takes format, in the body or as ?format= in the query (send it once; two different values are a 400). The price is the same in all three, because you pay for the document, not for the file it arrives in.
format | What comes back | Kept |
|---|---|---|
pdf (default) | JSON with the PDF url, page_count and expires_at | 24 hours, or retain_days |
html | The document itself, Content-Type: text/html | not kept |
markdown | The same document as Markdown, Content-Type: text/markdown | not kept |
HTML is one self-contained file: styles inline, the chart wheel and the Vastu plan as inline SVG, no scripts and no external fonts. It is the same page the PDF is printed from, with the same white-label block: your company name, report title, colours and footer. The one outside reference is your own logoUrl, left as a link to your https image, exactly as in the PDF. Every name, place and text you send is escaped, so a name like <img onerror=...> prints as text. Safe to drop into your page or an iframe.
Markdown carries the same headings, text and tables. Headings keep their level: # is the report title, ## a section, ### a subsection, in the same order as the PDF, so splitting on lines that start with ## gives you the sections. Tables are GitHub-style tables. A drawing (the wheel, a plan) is left out with a one-line note in its place. Any character that Markdown or an HTML-passing renderer would read as markup is backslash-escaped.
curl -X POST "https://api.astroway.info/v1/reports/natal?format=markdown" \ -H "X-Api-Key: aw_live_..." -H "Content-Type: application/json" \ -d '{ "chart": { "date": "1990-05-15", "time": "14:30:00", "timezoneOffset": 3, "latitude": 50.45, "longitude": 30.52 }, "language": "en" }'The PDF link lives for 24 hours. To hand a client a link that lasts, add ?retain_days=30 (up to 90): the file stays that many days and expires_at in the response says so. We do not host other people’s documents indefinitely, and you can delete a file sooner with DELETE /v1/reports/files/{filename}, free. The file holds what you sent, the name included, which is why its retention is in the DPA, section 2. GET /v1/reports/history is free and lists this key’s recent exports; an expired row comes back with expired: true.
Your brand, not ours
Section titled “Your brand, not ours”whitelabel takes an object of 15 fields: companyName, companyUrl, companyEmail, companyMobile, companyBio, logoUrl, frontImage, reportName, footerText, fontPairing and five colours (themeColor, headingColor, textPrimaryColor, textSecondaryColor, backgroundColor).
You can pass it inline, which means no account configuration at all:
curl -X POST https://api.astroway.info/v1/reports/natal \ -H "X-Api-Key: aw_live_..." \ -H "Content-Type: application/json" \ -d '{ "chart": { "date": "1990-05-15", "time": "14:30:00", "timezoneOffset": 3, "latitude": 50.45, "longitude": 30.52 }, "whitelabel": { "companyName": "Zoryana Studio", "reportName": "Your Birth Blueprint", "themeColor": "#7c3aed", "footerText": "zoryana.example" } }'The generated document carries the studio name, that report title, the accent colour on section headings and your footer. The word AstroWay does not appear in it once.
If you would rather not repeat the object on every call, whitelabel: true uses the account configuration. Set it on the Report branding page of the dashboard: company name, report title, contacts, logo upload and two colours, with a preview of a sample natal report. The same settings are at /v1/whitelabel/config and /v1/whitelabel/logo for a key, and POST /v1/whitelabel/preview renders the sample as a PDF. A field sent inline in the object wins over the saved one.
A working app you can clone
Section titled “A working app you can clone”Live demo and the code on GitHub, MIT.
A practitioner’s desk: client details on the left, a finished PDF on the right. Every report tile shows its credit price before the click and links a finished sample. White-label is a checkbox. The backend is one route and no dependencies, because that is the point: a browser cannot reach the API directly, so the key lives on the server.
git clone https://github.com/astroway/starter-practicecd starter-practice && npm installcp .env.example .env # your key goes herenpm run devFour things worth taking. The cost is shown where the decision is made: the server hands X-Credits-Used back to the page rather than only to a log. Sixteen reports take four request shapes, not sixteen. The same input twice costs nothing, because the response cache returns the same file. And ALLOWED_REPORTS gates what an instance will render: the public demo renders the 100-credit tarot spread only, because a page on the open internet that will produce a 5,000-credit natal report for anyone spends a month’s free tier in two clicks.
Languages
Section titled “Languages”The language field accepts 21 codes. Three are fully translated: Ukrainian, English, Russian. For the other eighteen the sign names localise and the headings and explanations stay English, so a German report says “Löwe” under a heading that reads “Planets”.
We say so plainly, because a report is a document your client keeps. Selling it as German after seeing German sign names in a sample would be an unpleasant discovery on their side rather than ours. The muhurta report is still entirely English. The vastu, bazi, numerology, kundli-matching and chinese-year reports are written in Ukrainian and English; any other language gets the English document rather than Ukrainian headings over English data. Write the name for numerology in Latin letters: the letter tables hold A to Z only, and a name in another script returns 400 NAME_NOT_LATIN rather than zeros.
How many reports a plan buys
Section titled “How many reports a plan buys”/v1/reports/natal and the rest of the PDFs cost 5000 credits, so a plan’s monthly allowance converts straight into a number of reports:
| Plan | Credits/mo | PDF reports | Tarot reports |
|---|---|---|---|
| Free | 10 000 | reports unavailable | unavailable |
| Indie, $5 | 50 000 | 10 | 500 |
| Starter, $19 | 200 000 | 40 | 2000 |
| Pro, $59 | 800 000 | 160 | 8000 |
| Business, $199 | 3 500 000 | 700 | 35000 |
| Reports Pack, $99 | 1 500 000 | 300 | 15000 |
Reports are closed on Free on purpose: each PDF takes seconds of rendering on our side and a free tier does not cover that. The cheapest way in is Indie at $5.
Reports Pack is a separate add-on for people who want reports and nothing else: $99 a month, 1 500 000 credits, which is 300 PDFs at 33 cents each, with white-label included. That is cheaper per PDF than Pro, because the key reaches nothing but reports. A key on that plan reaches /v1/reports/* and /v1/whitelabel/* only.
Reselling reports: what a PDF costs you
Section titled “Reselling reports: what a PDF costs you”If you sell reports to your own clients, the number that matters is what one PDF costs you at your volume. Inside a plan’s allowance that is the plan price divided by the PDFs it buys. Past the allowance every PDF is overage, charged per 10 000 credits over, so a 5000-credit PDF costs half the plan’s overage rate.
| Plan | PDFs included | Cost per PDF inside | Each PDF past it |
|---|---|---|---|
| Indie, $5 | 10 | $0.50 | $2.50 |
| Starter, $19 | 40 | $0.48 | $2.50 |
| Pro, $59 | 160 | $0.37 | $1.50 |
| Reports Pack, $99 | 300 | $0.33 | $1.50 |
| Business, $199 | 700 | $0.28 | $1.00 |
So the cheapest plan depends on how many PDFs you sell a month, overage included:
| PDFs a month | Cheapest plan | Your cost | Per PDF |
|---|---|---|---|
| 10 | Indie | $5 | $0.50 |
| 40 | Starter | $19 | $0.48 |
| 100 | Pro | $59 | $0.59 |
| 160 | Pro | $59 | $0.37 |
| 300 | Reports Pack | $99 | $0.33 |
| 500 | Business | $199 | $0.40 |
| 700 | Business | $199 | $0.28 |
The switch points: Starter beats Indie from 16 PDFs, Pro beats Starter from 57, Reports Pack beats Pro from 187 if you need nothing but reports, Business beats Reports Pack from 367. Pro and Business also open the rest of the API; the Pack opens reports and white-label only.
The margin is yours to set. At 300 PDFs on Reports Pack your cost is $99 a month. Sold at $9 each, that is $2700 in, $99 out; at $19 each, $5700 in. We do not suggest a retail price, but the arithmetic is the same at any price: what you charge minus 33 cents.
An extended natal report costs twice a standard one, so on every plan above it is twice the price per PDF: $0.66 on Reports Pack.
Two things lower the real cost further. A repeated request with the same input returns the same file from the response cache and costs nothing, so a client who downloads their report twice is billed once. And a yearly plan is 12 months for the price of 9, which takes Reports Pack to $0.25 a PDF.
Before you sell, open the samples: each is the exact file the API returns, and with whitelabel your name and colours take the place of the defaults.
When you want the text, not the document
Section titled “When you want the text, not the document”Five endpoints return an AI narrative as JSON, with no layout and no PDF: /v1/reports/ai/natal-narrative, /transit-narrative, /synastry-narrative, /year-ahead-narrative, /monthly-narrative. 250 credits each. Use them when the text goes into your own layout, app or newsletter.
The natal report also does both at once: enrich: true puts an AI narrative inside the PDF. On the same test chart that is 5 pages instead of 3.