Astrology report software for white-label PDFs

Generate a personalised natal chart, kundli, human design, BaZi or numerology report under your own brand with one API call. A print-ready PDF, a self-contained web page or Markdown, in the language of your client, on every plan.

A report is a finished document built from the same data the chart endpoints return: the wheel or the kundli drawn to its tradition, every placement in a table, and the reading for each one, laid out page by page with your name, logo, colours, font and footer. You send the birth details, you get the document back. This page is for developers generating reports in an app or a backend, and for sellers who want to know what the widget does underneath. Samples, the full catalogue and what each report contains are on white label astrology reports.

The report operations

Each report is one POST operation under the Reports tag, at /api/v2/reports/{id}, named generate{Report}Report.

The spec is the live list, with the cost of each report beside it:

curl -s https://roxyapi.com/api/v2/openapi.json \
  | jq -r '.paths | to_entries[] | select(.key | startswith("/reports/")) | "\(.key)  \(.value.post.operationId)  \(.value.post["x-request-cost"])"'

Every operation, with its request schema and a live console, is in the Reports API reference.

What the request carries

The body is the input of the chart the report is built on, plus four report fields. A natal report takes what POST /astrology/natal-chart takes, a kundli report what the Vedic birth chart takes, a synastry or matching report person1 and person2, a numerology report fullName, year, month and day. A tarot report needs nothing: send a question if your client has one.

Birth places follow the same rule as every chart: resolve the city with GET /location/search and send its latitude, longitude and IANA timezone. Never ask your client for coordinates.

Generate a PDF

Get your API key, then request the report and decode the pdf field into a file.

curl -s -X POST "https://roxyapi.com/api/v2/reports/natal" \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": "America/New_York",
    "format": "pdf"
  }' | jq -r .pdf | base64 --decode > natal-report.pdf

import { writeFile } from 'node:fs/promises';

const res = await fetch('https://roxyapi.com/api/v2/reports/natal?lang=es', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.ROXY_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    date: '1990-07-15',
    time: '14:30:00',
    latitude: 40.7128,
    longitude: -74.006,
    timezone: 'America/New_York',
    format: 'pdf',
    branding: {
      name: 'Luna Rivera Astrology',
      footer: 'For reflection. Book a reading at example.com.',
      colors: { primary: '#3e2a2c', accent: '#914955' },
    },
  }),
});
const report = await res.json();
if (!res.ok) throw new Error(`${report.code}: ${report.error}`);

await writeFile(`${report.title}.pdf`, Buffer.from(report.pdf, 'base64'));
console.log(report.title, report.pages);

import base64, os, requests

res = requests.post(
    "https://roxyapi.com/api/v2/reports/tarot",
    params={"lang": "en"},
    headers={"X-API-Key": os.environ["ROXY_API_KEY"]},
    json={"question": "What should I focus on this month?", "format": "pdf"},
)
report = res.json()
if not res.ok:
    raise RuntimeError(f'{report["code"]}: {report["error"]}')

with open("tarot-reading.pdf", "wb") as f:
    f.write(base64.b64decode(report["pdf"]))
print(report["title"], report["pages"])

The JavaScript call above returns a Spanish natal report titled Informe de carta natal, saved under that name.

The response

A JSON object with the document in one field, chosen by format.

Branding

Send branding with every request. Every field is optional, and anything left out keeps the theme value. The document carries your brand alone, on every plan.

The logo URL must answer with the image file itself. A page that only shows the image, a host that answers an error, or a file over the size limit returns a 400: see invalid_branding and logo_fetch_failed.

Languages

Add ?lang= and the whole report changes language: cover, headings, table labels and every reading. A Spanish natal report is POST /api/v2/reports/natal?lang=es. The supported codes are on the lang parameter of each operation in the API reference, and an unsupported code returns a 400 listing them.

HTML and Markdown

format: "html" returns the report as one HTML document with everything inline, so you can store it or serve it as a page without fetching anything else. format: "markdown" returns the text of the report as CommonMark for your own template; the charts are drawn in the PDF and HTML formats.

The report widget for browsers

Selling from a website? The report widget runs in the browser of your visitor with a publishable key, asks for the birth details the report needs, and hands back the PDF or shows the report on the page. Copy it from the report builder, which writes every setting for you:

<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js" defer></script>
<div data-roxy-widget="report" data-publishable-key="pk_live_YOUR_KEY" data-report="natal" data-format="pdf" data-brand-name="Luna Rivera Astrology" data-brand-footer="Book a reading at lunarivera.com" data-brand-color="#3e2a2c" data-brand-accent="#914955" data-font="jost"></div>

data-report takes the report id from the table above and data-format takes pdf or html. Every option, the component tag form and the platform walkthroughs: widgets guide. The widget generates a report for anyone who reaches the page, so put it on the page your checkout unlocks; your own platform takes the payment.

What a report costs

Every data endpoint is one request. A report is a whole document built from many calculations and readings, so each report states its cost in requests up front: x-request-cost on its operation in the spec, the jq command above, and the cost table on /reports, which also shows how many of each report every plan covers a month. A report draws from the same monthly plan as every other call, with no separate packs and no tier gate. A request that fails on our side with a 5xx does not count.

What is never stored

A report is generated when you ask for it and handed straight back. The birth details, the branding, the logo and the finished file are never stored, so keep the response if you want to send it again. Branding travels with each request for the same reason.

Errors

A failure is { error, code, doc_url }, and a 400 adds issues[] naming every field at fault. The report-specific codes:

FAQ

Next steps

• White label astrology reports: samples, the full catalogue and the cost table.
• How to sell astrology readings: the no-code path from builder to checkout page.
• Reports API reference: every operation with a live console.
• Caching and cost: keep the documents you have already generated.