Reports API Reference

Branded reports built from the API: a natal chart and more as a print-ready PDF, self-contained HTML or Markdown, white-labelled with your name, logo, colours and typeface, in every supported language.

Auth: X-API-Key
Languages: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant
SDKs: TypeScript, Python, PHP, C#, Go, and Rust

POST /api/v2/reports/natal

Natal chart report

Renders the natal chart report from the same input as its chart, as a white-label document under your name, logo, colours and typeface. Like every template in the reports catalogue, it returns a print-ready PDF, self-contained HTML or Markdown, in the language set by lang.

Request

date string (date), required: Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day.
time string (time), required: Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown.
latitude number, required: Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South.
longitude number, required: Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West.
timezone number or string, required: Timezone: an IANA name (e.g. "America/New_York", "Europe/London", or `cities[0].timezone` from /location/search) or decimal hours from UTC (e.g. -5 for EST, 5.5 for IST). An IANA name is resolved to the offset in force at the given date and time.

Show all 18 optional fieldsShow fewer optional fields

lang query, string enum: Report language (BCP 47): the labels, headings and readings are written in it. Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. One of en, tr, de, es, hi, pt, fr, ru. Default en.
nodeType string enum: Lunar node convention. "mean" is the smoothed average node, which always moves retrograde; "true" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass "mean" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to "true". One of mean, true.
houseSystem string enum: House system for dividing the chart into 12 houses. Placidus (default) is most popular in Western astrology and time-sensitive. Whole Sign assigns one sign per house (simpler, ancient). Equal houses divide chart into 30° segments from Ascendant. Koch emphasizes houses in high latitudes. One of placidus, whole-sign, equal, koch.
format string enum: Output format: pdf (a print-ready PDF, base64 in the pdf field), html (one self-contained HTML document in the html field) or markdown (CommonMark in the markdown field). One of pdf, html, markdown.
branding object: White-label branding for this report. Every field is optional and nothing is stored: send it with each request.
branding.name string: Business or practitioner name printed on the cover and in the running header of every page.
branding.logo string (uri): HTTPS URL of a PNG, JPEG, WebP or SVG logo under 1 MB, printed on the cover. It is fetched for this report only and never stored.
branding.footer string: Line printed at the foot of every page, such as a disclaimer or a booking note.
branding.website string (uri): Website printed on the cover.
branding.email string (email): Contact email printed on the cover.
branding.colors object: Brand colours. Each one left out keeps the theme colour.
branding.colors.primary string: Headings and table headers, as a six digit hex colour.
branding.colors.accent string: Rules and highlights, as a six digit hex colour.
branding.font string enum: Font pair for headings and text, the same pairs the RoxyAPI UI components take. Left out, the theme typeface is used. One of fraunces-jost, jost, geist, system.
branding.theme string enum: Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used. One of celeste, eucalyptus, kiln, moonlit, practitioner.
page object: Page layout of the PDF.
page.size string enum: Paper size of the PDF. Ignored by html and markdown. One of A4, Letter.
readings boolean: Whether the report carries its written readings. false keeps the charts, tables and key figures and leaves out every interpretation, for a chart-only report at the same cost.

Response

template string, required: The report template rendered.
lang string, required: Language the report is written in.
format string enum, required: Format of the output field present. One of pdf, html, markdown.
title string, required: Report title in the report language, ready for a file name or a heading.
pages integer: Number of PDF pages. Present when format is pdf.
pdf string: The PDF, base64 encoded. Present when format is pdf: decode it and save it as a .pdf file.
html string: The report as one self-contained HTML document. Present when format is html.
markdown string: The report as CommonMark. Present when format is markdown.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /reports/natal

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.reports.generateNatalReport({ body: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York' } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.reports.generate_natal_report(date='1990-07-15', time='14:30:00', latitude=40.7128, longitude=-74.006, timezone='America/New_York')

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->reports->generateNatalReport(date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York');

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Reports.Natal.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Reports.GenerateNatalReport(ctx, nil, roxyapi.GenerateNatalReportJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateNatalReportParams, body: &types::NatalReportRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.reports().generate_natal_report(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/reports/natal" \
  -H "X-API-Key: YOUR_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"}'

Edit values

lang

Request body

Example response

{
  "template": "natal",
  "lang": "en",
  "format": "pdf",
  "title": "Natal chart report",
  "pages": 24,
  "pdf": "JVBERi0xLjcK",
  "html": "<!doctype html><html lang=\"en\">",
  "markdown": "# Natal chart report"
}

POST /api/v2/reports/synastry

Synastry report

Renders the synastry report from the same input as its chart, as a white-label document under your name, logo, colours and typeface. Like every template in the reports catalogue, it returns a print-ready PDF, self-contained HTML or Markdown, in the language set by lang.

Request

person1 object, required
person1.date string (date), required: Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day.
person1.time string (time), required: Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown.
person1.latitude number, required: Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South.
person1.longitude number, required: Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West.
person1.timezone number or string, required: Timezone: an IANA name (e.g. "America/New_York", "Europe/London", or `cities[0].timezone` from /location/search) or decimal hours from UTC (e.g. -5 for EST, 5.5 for IST). An IANA name is resolved to the offset in force at the given date and time.
person2 object, required
person2.date string (date), required: Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day.
person2.time string (time), required: Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown.
person2.latitude number, required: Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South.
person2.longitude number, required: Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West.
person2.timezone number or string, required: Timezone: an IANA name (e.g. "America/New_York", "Europe/London", or `cities[0].timezone` from /location/search) or decimal hours from UTC (e.g. -5 for EST, 5.5 for IST). An IANA name is resolved to the offset in force at the given date and time.

Show all 21 optional fieldsShow fewer optional fields

lang query, string enum: Report language (BCP 47): the labels, headings and readings are written in it. Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. One of en, tr, de, es, hi, pt, fr, ru. Default en.
person1.nodeType string enum: Lunar node convention. "mean" is the smoothed average node, which always moves retrograde; "true" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass "mean" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to "true". One of mean, true.
person1.name string: Optional display name for this person. Included in the response for easy identification.
person2.nodeType string enum: Lunar node convention. "mean" is the smoothed average node, which always moves retrograde; "true" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass "mean" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to "true". One of mean, true.
person2.name string: Optional display name for this person. Included in the response for easy identification.
houseSystem string enum: House system for both natal charts. Placidus (default), Whole Sign, Equal, or Koch. One of placidus, whole-sign, equal, koch.
format string enum: Output format: pdf (a print-ready PDF, base64 in the pdf field), html (one self-contained HTML document in the html field) or markdown (CommonMark in the markdown field). One of pdf, html, markdown.
branding object: White-label branding for this report. Every field is optional and nothing is stored: send it with each request.
branding.name string: Business or practitioner name printed on the cover and in the running header of every page.
branding.logo string (uri): HTTPS URL of a PNG, JPEG, WebP or SVG logo under 1 MB, printed on the cover. It is fetched for this report only and never stored.
branding.footer string: Line printed at the foot of every page, such as a disclaimer or a booking note.
branding.website string (uri): Website printed on the cover.
branding.email string (email): Contact email printed on the cover.
branding.colors object: Brand colours. Each one left out keeps the theme colour.
branding.colors.primary string: Headings and table headers, as a six digit hex colour.
branding.colors.accent string: Rules and highlights, as a six digit hex colour.
branding.font string enum: Font pair for headings and text, the same pairs the RoxyAPI UI components take. Left out, the theme typeface is used. One of fraunces-jost, jost, geist, system.
branding.theme string enum: Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used. One of celeste, eucalyptus, kiln, moonlit, practitioner.
page object: Page layout of the PDF.
page.size string enum: Paper size of the PDF. Ignored by html and markdown. One of A4, Letter.
readings boolean: Whether the report carries its written readings. false keeps the charts, tables and key figures and leaves out every interpretation, for a chart-only report at the same cost.

Response

template string, required: The report template rendered.
lang string, required: Language the report is written in.
format string enum, required: Format of the output field present. One of pdf, html, markdown.
title string, required: Report title in the report language, ready for a file name or a heading.
pages integer: Number of PDF pages. Present when format is pdf.
pdf string: The PDF, base64 encoded. Present when format is pdf: decode it and save it as a .pdf file.
html string: The report as one self-contained HTML document. Present when format is html.
markdown string: The report as CommonMark. Present when format is markdown.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /reports/synastry

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.reports.generateSynastryReport({ body: { person1: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York', nodeType: 'true', name: 'Alex' }, person2: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York', nodeType: 'true', name: 'Alex' } } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.reports.generate_synastry_report(person1={'date': '1990-07-15', 'time': '14:30:00', 'latitude': 40.7128, 'longitude': -74.006, 'timezone': 'America/New_York', 'nodeType': 'true', 'name': 'Alex'}, person2={'date': '1990-07-15', 'time': '14:30:00', 'latitude': 40.7128, 'longitude': -74.006, 'timezone': 'America/New_York', 'nodeType': 'true', 'name': 'Alex'})

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->reports->generateSynastryReport(person1: ['date' => '1990-07-15', 'time' => '14:30:00', 'latitude' => 40.7128, 'longitude' => -74.006, 'timezone' => 'America/New_York', 'nodeType' => 'true', 'name' => 'Alex'], person2: ['date' => '1990-07-15', 'time' => '14:30:00', 'latitude' => 40.7128, 'longitude' => -74.006, 'timezone' => 'America/New_York', 'nodeType' => 'true', 'name' => 'Alex']);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Reports.Synastry.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Reports.GenerateSynastryReport(ctx, nil, roxyapi.GenerateSynastryReportJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateSynastryReportParams, body: &types::SynastryReportRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.reports().generate_synastry_report(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/reports/synastry" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person1":{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York","nodeType":"true","name":"Alex"},"person2":{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York","nodeType":"true","name":"Alex"}}'

Edit values

lang

Request body

Example response

{
  "template": "synastry",
  "lang": "en",
  "format": "pdf",
  "title": "Synastry report",
  "pages": 24,
  "pdf": "JVBERi0xLjcK",
  "html": "<!doctype html><html lang=\"en\">",
  "markdown": "# Synastry report"
}

POST /api/v2/reports/kundli

Kundli report

Renders the kundli report from the same input as its chart, as a white-label document under your name, logo, colours and typeface. Like every template in the reports catalogue, it returns a print-ready PDF, self-contained HTML or Markdown, in the language set by lang.

Request

date string (date), required: Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas).
time string (time), required: Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect.
latitude number, required: Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172.
longitude number, required: Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240.

Show all 19 optional fieldsShow fewer optional fields

lang query, string enum: Report language (BCP 47): the labels, headings and readings are written in it. Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. One of en, tr, de, es, hi, pt, fr, ru. Default en.
timezone number or string: Timezone: an IANA name (e.g. "America/New_York", "Europe/London", or `cities[0].timezone` from /location/search) or decimal hours from UTC (e.g. -5 for EST, 5.5 for IST). An IANA name is resolved to the offset in force at the given date and time. Defaults to 5.5.
ayanamsa string enum: Sidereal frame (ayanamsa) the chart is cast in. "lahiri" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. "raman" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. "kp-newcomb" and "kp-old" are the two Krishnamurti Paddhati frames. "custom" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it. One of kp-newcomb, kp-old, lahiri, raman, custom.
ayanamsaValue number: Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source.
format string enum: Output format: pdf (a print-ready PDF, base64 in the pdf field), html (one self-contained HTML document in the html field) or markdown (CommonMark in the markdown field). One of pdf, html, markdown.
branding object: White-label branding for this report. Every field is optional and nothing is stored: send it with each request.
branding.name string: Business or practitioner name printed on the cover and in the running header of every page.
branding.logo string (uri): HTTPS URL of a PNG, JPEG, WebP or SVG logo under 1 MB, printed on the cover. It is fetched for this report only and never stored.
branding.footer string: Line printed at the foot of every page, such as a disclaimer or a booking note.
branding.website string (uri): Website printed on the cover.
branding.email string (email): Contact email printed on the cover.
branding.colors object: Brand colours. Each one left out keeps the theme colour.
branding.colors.primary string: Headings and table headers, as a six digit hex colour.
branding.colors.accent string: Rules and highlights, as a six digit hex colour.
branding.font string enum: Font pair for headings and text, the same pairs the RoxyAPI UI components take. Left out, the theme typeface is used. One of fraunces-jost, jost, geist, system.
branding.theme string enum: Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used. One of celeste, eucalyptus, kiln, moonlit, practitioner.
page object: Page layout of the PDF.
page.size string enum: Paper size of the PDF. Ignored by html and markdown. One of A4, Letter.
readings boolean: Whether the report carries its written readings. false keeps the charts, tables and key figures and leaves out every interpretation, for a chart-only report at the same cost.

Response

template string, required: The report template rendered.
lang string, required: Language the report is written in.
format string enum, required: Format of the output field present. One of pdf, html, markdown.
title string, required: Report title in the report language, ready for a file name or a heading.
pages integer: Number of PDF pages. Present when format is pdf.
pdf string: The PDF, base64 encoded. Present when format is pdf: decode it and save it as a .pdf file.
html string: The report as one self-contained HTML document. Present when format is html.
markdown string: The report as CommonMark. Present when format is markdown.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /reports/kundli

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.reports.generateKundliReport({ body: { date: '1990-07-04', time: '10:12:00', latitude: 28.6139, longitude: 77.209 } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.reports.generate_kundli_report(date='1990-07-04', time='10:12:00', latitude=28.6139, longitude=77.209)

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->reports->generateKundliReport(date: '1990-07-04', time: '10:12:00', latitude: 28.6139, longitude: 77.209);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Reports.Kundli.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Reports.GenerateKundliReport(ctx, nil, roxyapi.GenerateKundliReportJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateKundliReportParams, body: &types::KundliReportRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.reports().generate_kundli_report(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/reports/kundli" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-07-04","time":"10:12:00","latitude":28.6139,"longitude":77.209}'

Edit values

lang

Request body

Example response

{
  "template": "kundli",
  "lang": "en",
  "format": "pdf",
  "title": "Kundli report",
  "pages": 24,
  "pdf": "JVBERi0xLjcK",
  "html": "<!doctype html><html lang=\"en\">",
  "markdown": "# Kundli report"
}

POST /api/v2/reports/matchmaking

Kundli matching report

Renders the kundli matching report from the same input as its chart, as a white-label document under your name, logo, colours and typeface. Like every template in the reports catalogue, it returns a print-ready PDF, self-contained HTML or Markdown, in the language set by lang.

Request

person1 object, required: Birth data of the first person (typically the boy/groom in traditional Ashtakoot matching). Date, time, and location determine Moon nakshatra for koota scoring.
person1.date string (date), required: Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas).
person1.time string (time), required: Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect.
person1.latitude number, required: Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172.
person1.longitude number, required: Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240.
person2 object, required: Birth data of the second person (typically the girl/bride in traditional Ashtakoot matching). Moon nakshatra compared against person 1 across all 8 kootas.
person2.date string (date), required: Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas).
person2.time string (time), required: Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect.
person2.latitude number, required: Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172.
person2.longitude number, required: Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240.

Show all 20 optional fieldsShow fewer optional fields

lang query, string enum: Report language (BCP 47): the labels, headings and readings are written in it. Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. One of en, tr, de, es, hi, pt, fr, ru. Default en.
person1.timezone number or string: Timezone: an IANA name (e.g. "America/New_York", "Europe/London", or `cities[0].timezone` from /location/search) or decimal hours from UTC (e.g. -5 for EST, 5.5 for IST). An IANA name is resolved to the offset in force at the given date and time. Defaults to 5.5.
person2.timezone number or string: Timezone: an IANA name (e.g. "America/New_York", "Europe/London", or `cities[0].timezone` from /location/search) or decimal hours from UTC (e.g. -5 for EST, 5.5 for IST). An IANA name is resolved to the offset in force at the given date and time. Defaults to 5.5.
ayanamsa string enum: Sidereal frame (ayanamsa) the chart is cast in. "lahiri" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. "raman" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. "kp-newcomb" and "kp-old" are the two Krishnamurti Paddhati frames. "custom" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it. One of kp-newcomb, kp-old, lahiri, raman, custom.
ayanamsaValue number: Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source.
format string enum: Output format: pdf (a print-ready PDF, base64 in the pdf field), html (one self-contained HTML document in the html field) or markdown (CommonMark in the markdown field). One of pdf, html, markdown.
branding object: White-label branding for this report. Every field is optional and nothing is stored: send it with each request.
branding.name string: Business or practitioner name printed on the cover and in the running header of every page.
branding.logo string (uri): HTTPS URL of a PNG, JPEG, WebP or SVG logo under 1 MB, printed on the cover. It is fetched for this report only and never stored.
branding.footer string: Line printed at the foot of every page, such as a disclaimer or a booking note.
branding.website string (uri): Website printed on the cover.
branding.email string (email): Contact email printed on the cover.
branding.colors object: Brand colours. Each one left out keeps the theme colour.
branding.colors.primary string: Headings and table headers, as a six digit hex colour.
branding.colors.accent string: Rules and highlights, as a six digit hex colour.
branding.font string enum: Font pair for headings and text, the same pairs the RoxyAPI UI components take. Left out, the theme typeface is used. One of fraunces-jost, jost, geist, system.
branding.theme string enum: Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used. One of celeste, eucalyptus, kiln, moonlit, practitioner.
page object: Page layout of the PDF.
page.size string enum: Paper size of the PDF. Ignored by html and markdown. One of A4, Letter.
readings boolean: Whether the report carries its written readings. false keeps the charts, tables and key figures and leaves out every interpretation, for a chart-only report at the same cost.

Response

template string, required: The report template rendered.
lang string, required: Language the report is written in.
format string enum, required: Format of the output field present. One of pdf, html, markdown.
title string, required: Report title in the report language, ready for a file name or a heading.
pages integer: Number of PDF pages. Present when format is pdf.
pdf string: The PDF, base64 encoded. Present when format is pdf: decode it and save it as a .pdf file.
html string: The report as one self-contained HTML document. Present when format is html.
markdown string: The report as CommonMark. Present when format is markdown.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /reports/matchmaking

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.reports.generateMatchmakingReport({ body: { person1: { date: '1990-07-04', time: '10:12:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 }, person2: { date: '1990-07-04', time: '10:12:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 } } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.reports.generate_matchmaking_report(person1={'date': '1990-07-04', 'time': '10:12:00', 'latitude': 28.6139, 'longitude': 77.209, 'timezone': 5.5}, person2={'date': '1990-07-04', 'time': '10:12:00', 'latitude': 28.6139, 'longitude': 77.209, 'timezone': 5.5})

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->reports->generateMatchmakingReport(person1: ['date' => '1990-07-04', 'time' => '10:12:00', 'latitude' => 28.6139, 'longitude' => 77.209, 'timezone' => 5.5], person2: ['date' => '1990-07-04', 'time' => '10:12:00', 'latitude' => 28.6139, 'longitude' => 77.209, 'timezone' => 5.5]);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Reports.Matchmaking.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Reports.GenerateMatchmakingReport(ctx, nil, roxyapi.GenerateMatchmakingReportJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateMatchmakingReportParams, body: &types::MatchmakingReportRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.reports().generate_matchmaking_report(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/reports/matchmaking" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person1":{"date":"1990-07-04","time":"10:12:00","latitude":28.6139,"longitude":77.209,"timezone":5.5},"person2":{"date":"1990-07-04","time":"10:12:00","latitude":28.6139,"longitude":77.209,"timezone":5.5}}'

Edit values

lang

Request body

Example response

{
  "template": "matchmaking",
  "lang": "en",
  "format": "pdf",
  "title": "Kundli matching report",
  "pages": 24,
  "pdf": "JVBERi0xLjcK",
  "html": "<!doctype html><html lang=\"en\">",
  "markdown": "# Kundli matching report"
}

POST /api/v2/reports/yearly-forecast

Yearly forecast report

Renders the yearly forecast report from the same input as its chart, as a white-label document under your name, logo, colours and typeface. Like every template in the reports catalogue, it returns a print-ready PDF, self-contained HTML or Markdown, in the language set by lang.

Request

date string (date), required: Birth date in YYYY-MM-DD format. Anchors the natal Sun longitude the transiting Sun returns to each year.
time string (time), required: Birth time in 24-hour HH:MM:SS format. Pins the exact natal Sun position that defines the solar return moment.
year integer, required: Year to cast the solar return for. The chart is erected for the moment in this year when the transiting Sun returns to the natal Sun longitude, on or within a day of the birthday.
latitude number, required: Latitude of the solar return location in decimal degrees. The solar return is location-sensitive: use the birthplace to anchor the chart to natal geography, or the current city for a relocated solar return.
longitude number, required: Longitude of the solar return location in decimal degrees. Sets the local sidereal time, so it drives the Ascendant, Midheaven, and house cusps of the return chart.
timezone number or string, required: IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.

Show all 17 optional fieldsShow fewer optional fields

lang query, string enum: Report language (BCP 47): the labels, headings and readings are written in it. Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. One of en, tr, de, es, hi, pt, fr, ru. Default en.
houseSystem string enum: House system for the return chart. placidus is the Western default. whole-sign, equal, and koch are also supported. One of placidus, whole-sign, equal, koch.
format string enum: Output format: pdf (a print-ready PDF, base64 in the pdf field), html (one self-contained HTML document in the html field) or markdown (CommonMark in the markdown field). One of pdf, html, markdown.
branding object: White-label branding for this report. Every field is optional and nothing is stored: send it with each request.
branding.name string: Business or practitioner name printed on the cover and in the running header of every page.
branding.logo string (uri): HTTPS URL of a PNG, JPEG, WebP or SVG logo under 1 MB, printed on the cover. It is fetched for this report only and never stored.
branding.footer string: Line printed at the foot of every page, such as a disclaimer or a booking note.
branding.website string (uri): Website printed on the cover.
branding.email string (email): Contact email printed on the cover.
branding.colors object: Brand colours. Each one left out keeps the theme colour.
branding.colors.primary string: Headings and table headers, as a six digit hex colour.
branding.colors.accent string: Rules and highlights, as a six digit hex colour.
branding.font string enum: Font pair for headings and text, the same pairs the RoxyAPI UI components take. Left out, the theme typeface is used. One of fraunces-jost, jost, geist, system.
branding.theme string enum: Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used. One of celeste, eucalyptus, kiln, moonlit, practitioner.
page object: Page layout of the PDF.
page.size string enum: Paper size of the PDF. Ignored by html and markdown. One of A4, Letter.
readings boolean: Whether the report carries its written readings. false keeps the charts, tables and key figures and leaves out every interpretation, for a chart-only report at the same cost.

Response

template string, required: The report template rendered.
lang string, required: Language the report is written in.
format string enum, required: Format of the output field present. One of pdf, html, markdown.
title string, required: Report title in the report language, ready for a file name or a heading.
pages integer: Number of PDF pages. Present when format is pdf.
pdf string: The PDF, base64 encoded. Present when format is pdf: decode it and save it as a .pdf file.
html string: The report as one self-contained HTML document. Present when format is html.
markdown string: The report as CommonMark. Present when format is markdown.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /reports/yearly-forecast

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.reports.generateYearlyForecastReport({ body: { date: '1990-07-15', time: '14:30:00', year: 2026, latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York' } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.reports.generate_yearly_forecast_report(date='1990-07-15', time='14:30:00', year=2026, latitude=40.7128, longitude=-74.006, timezone='America/New_York')

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->reports->generateYearlyForecastReport(date: '1990-07-15', time: '14:30:00', year: 2026, latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York');

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Reports.YearlyForecast.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Reports.GenerateYearlyForecastReport(ctx, nil, roxyapi.GenerateYearlyForecastReportJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateYearlyForecastReportParams, body: &types::YearlyForecastReportRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.reports().generate_yearly_forecast_report(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/reports/yearly-forecast" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-07-15","time":"14:30:00","year":2026,"latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York"}'

Edit values

lang

Request body

Example response

{
  "template": "yearly-forecast",
  "lang": "en",
  "format": "pdf",
  "title": "Yearly forecast report",
  "pages": 24,
  "pdf": "JVBERi0xLjcK",
  "html": "<!doctype html><html lang=\"en\">",
  "markdown": "# Yearly forecast report"
}

POST /api/v2/reports/human-design

Human Design report

Renders the human design report from the same input as its chart, as a white-label document under your name, logo, colours and typeface. Like every template in the reports catalogue, it returns a print-ready PDF, self-contained HTML or Markdown, in the language set by lang.

Request

date string (date), required: Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier.
time string (time), required: Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth.
timezone number or string, required: IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.

Show all 19 optional fieldsShow fewer optional fields

lang query, string enum: Report language (BCP 47): the labels, headings and readings are written in it. Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. One of en, tr, de, es, hi, pt, fr, ru. Default en.
latitude number: Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0.
longitude number: Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0.
nodeType string enum: Lunar node convention. "mean" is the smoothed average node, which always moves retrograde; "true" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice moves a node gate. Because a gate can be half of a channel, that can change the completed channels and, with them, whether a center reads defined or open, plus the definition, authority, profile or type. A chart where only one center disagrees is the usual shape, since the type and profile often survive unchanged. If another calculator disagrees on any of those, it is almost certainly using the mean node: pass "mean" to match it. Defaults to "true". One of mean, true.
format string enum: Output format: pdf (a print-ready PDF, base64 in the pdf field), html (one self-contained HTML document in the html field) or markdown (CommonMark in the markdown field). One of pdf, html, markdown.
branding object: White-label branding for this report. Every field is optional and nothing is stored: send it with each request.
branding.name string: Business or practitioner name printed on the cover and in the running header of every page.
branding.logo string (uri): HTTPS URL of a PNG, JPEG, WebP or SVG logo under 1 MB, printed on the cover. It is fetched for this report only and never stored.
branding.footer string: Line printed at the foot of every page, such as a disclaimer or a booking note.
branding.website string (uri): Website printed on the cover.
branding.email string (email): Contact email printed on the cover.
branding.colors object: Brand colours. Each one left out keeps the theme colour.
branding.colors.primary string: Headings and table headers, as a six digit hex colour.
branding.colors.accent string: Rules and highlights, as a six digit hex colour.
branding.font string enum: Font pair for headings and text, the same pairs the RoxyAPI UI components take. Left out, the theme typeface is used. One of fraunces-jost, jost, geist, system.
branding.theme string enum: Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used. One of celeste, eucalyptus, kiln, moonlit, practitioner.
page object: Page layout of the PDF.
page.size string enum: Paper size of the PDF. Ignored by html and markdown. One of A4, Letter.
readings boolean: Whether the report carries its written readings. false keeps the charts, tables and key figures and leaves out every interpretation, for a chart-only report at the same cost.

Response

template string, required: The report template rendered.
lang string, required: Language the report is written in.
format string enum, required: Format of the output field present. One of pdf, html, markdown.
title string, required: Report title in the report language, ready for a file name or a heading.
pages integer: Number of PDF pages. Present when format is pdf.
pdf string: The PDF, base64 encoded. Present when format is pdf: decode it and save it as a .pdf file.
html string: The report as one self-contained HTML document. Present when format is html.
markdown string: The report as CommonMark. Present when format is markdown.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /reports/human-design

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.reports.generateHumanDesignReport({ body: { date: '1990-07-15', time: '13:00:00', timezone: 'America/New_York' } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.reports.generate_human_design_report(date='1990-07-15', time='13:00:00', timezone='America/New_York')

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->reports->generateHumanDesignReport(date: '1990-07-15', time: '13:00:00', timezone: 'America/New_York');

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Reports.HumanDesign.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Reports.GenerateHumanDesignReport(ctx, nil, roxyapi.GenerateHumanDesignReportJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateHumanDesignReportParams, body: &types::HumanDesignReportRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.reports().generate_human_design_report(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/reports/human-design" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-07-15","time":"13:00:00","timezone":"America/New_York"}'

Edit values

lang

Request body

Example response

{
  "template": "human-design",
  "lang": "en",
  "format": "pdf",
  "title": "Human Design report",
  "pages": 24,
  "pdf": "JVBERi0xLjcK",
  "html": "<!doctype html><html lang=\"en\">",
  "markdown": "# Human Design report"
}

POST /api/v2/reports/bazi

BaZi report

Renders the bazi report from the same input as its chart, as a white-label document under your name, logo, colours and typeface. Like every template in the reports catalogue, it returns a print-ready PDF, self-contained HTML or Markdown, in the language set by lang.

Request

date string (date), required: Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary.
time string (time), required: Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere.
timezone number or string, required: IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
gender string enum, required: Subject sex, used only to pick the luck-pillar direction: a male born in a yang-stem year and a female born in a yin-stem year run forward through the sexagenary cycle, and the other two combinations run backward. It affects nothing else in the response. One of male, female.
year integer, required: Gregorian year the year-ahead section reads against the natal chart, and the first of the ten annual pillars the luck pillar section lists.

Show all 21 optional fieldsShow fewer optional fields

lang query, string enum: Report language (BCP 47): the labels, headings and readings are written in it. Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. One of en, tr, de, es, hi, pt, fr, ru. Default en.
latitude number: Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0.
longitude number: Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is "local-mean" or "solar", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is "clock".
dayBoundary string enum: Which instant starts the sexagenary DAY, which only matters for a birth between 23:00 and 23:59. "midnight" is the classical position of the Ming compendium San Ming Tong Hui: the day turns at 00:00 and 23:00 to 23:59 is the late zi hour of the day that is ending, so the hour stem is taken from that day. "early-zi" turns the whole day at 23:00, the practice in Hong Kong, Taiwan and much of South East Asia. "split-zi" is the compromise most software implements and the default here: the day still turns at 00:00, but the hour stem is taken from the next day. The three give three different answers for a late-evening birth and identical answers for every other birth. One of split-zi, midnight, early-zi.
yearBoundary string enum: Which instant starts the sexagenary YEAR. "li-chun" is Beginning of Spring, around 4 February, and is the classical rule every BaZi text uses, so it is the default on this endpoint. "lunar-new-year" is the folk rule people mean when they say which animal they are, and it falls between late January and late February. The two disagree for any birth in the weeks between them: 14 February 2026 is a Wood Snake year under lunar-new-year and a Fire Horse year under li-chun. One of li-chun, lunar-new-year.
hourClock string enum: Which clock the day boundary and the hour branch are read from, so a correction that carries a birth across midnight moves the day pillar with the hour. "clock" is civil time exactly as a birth certificate records it, which is what most calculators use and the default here. "local-mean" shifts to the mean sun over the birth longitude, a correction of up to 59 minutes at the edge of a wide time zone. "solar" adds the equation of time on top of that, up to a further 16 minutes. Both non-civil options need "longitude" in the request and return 400 without it. One of clock, local-mean, solar.
format string enum: Output format: pdf (a print-ready PDF, base64 in the pdf field), html (one self-contained HTML document in the html field) or markdown (CommonMark in the markdown field). One of pdf, html, markdown.
branding object: White-label branding for this report. Every field is optional and nothing is stored: send it with each request.
branding.name string: Business or practitioner name printed on the cover and in the running header of every page.
branding.logo string (uri): HTTPS URL of a PNG, JPEG, WebP or SVG logo under 1 MB, printed on the cover. It is fetched for this report only and never stored.
branding.footer string: Line printed at the foot of every page, such as a disclaimer or a booking note.
branding.website string (uri): Website printed on the cover.
branding.email string (email): Contact email printed on the cover.
branding.colors object: Brand colours. Each one left out keeps the theme colour.
branding.colors.primary string: Headings and table headers, as a six digit hex colour.
branding.colors.accent string: Rules and highlights, as a six digit hex colour.
branding.font string enum: Font pair for headings and text, the same pairs the RoxyAPI UI components take. Left out, the theme typeface is used. One of fraunces-jost, jost, geist, system.
branding.theme string enum: Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used. One of celeste, eucalyptus, kiln, moonlit, practitioner.
page object: Page layout of the PDF.
page.size string enum: Paper size of the PDF. Ignored by html and markdown. One of A4, Letter.
readings boolean: Whether the report carries its written readings. false keeps the charts, tables and key figures and leaves out every interpretation, for a chart-only report at the same cost.

Response

template string, required: The report template rendered.
lang string, required: Language the report is written in.
format string enum, required: Format of the output field present. One of pdf, html, markdown.
title string, required: Report title in the report language, ready for a file name or a heading.
pages integer: Number of PDF pages. Present when format is pdf.
pdf string: The PDF, base64 encoded. Present when format is pdf: decode it and save it as a .pdf file.
html string: The report as one self-contained HTML document. Present when format is html.
markdown string: The report as CommonMark. Present when format is markdown.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /reports/bazi

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.reports.generateBaziReport({ body: { date: '1990-06-15', time: '14:30:00', timezone: 'America/New_York', gender: 'male', year: 2027 } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.reports.generate_bazi_report(date='1990-06-15', time='14:30:00', timezone='America/New_York', gender='male', year=2027)

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->reports->generateBaziReport(date: '1990-06-15', time: '14:30:00', timezone: 'America/New_York', gender: 'male', year: 2027);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Reports.Bazi.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Reports.GenerateBaziReport(ctx, nil, roxyapi.GenerateBaziReportJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateBaziReportParams, body: &types::BaziReportRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.reports().generate_bazi_report(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/reports/bazi" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15","time":"14:30:00","timezone":"America/New_York","gender":"male","year":2027}'

Edit values

lang

Request body

Example response

{
  "template": "bazi",
  "lang": "en",
  "format": "pdf",
  "title": "BaZi report",
  "pages": 24,
  "pdf": "JVBERi0xLjcK",
  "html": "<!doctype html><html lang=\"en\">",
  "markdown": "# BaZi report"
}

POST /api/v2/reports/numerology

Numerology report

Renders the numerology report from the same input as its chart, as a white-label document under your name, logo, colours and typeface. Like every template in the reports catalogue, it returns a print-ready PDF, self-contained HTML or Markdown, in the language set by lang.

Request

fullName string, required: Full birth name as it appears on the birth certificate. Used for every letter-based number in the chart: Expression, Soul Urge, Personality, Karmic Lessons, Hidden Passion, Subconscious Self and the special letters. A name in any script is converted to Latin letters before it is counted, Cyrillic and Greek as the passport spelling and accents folded to the base letter, and the calculation lists the letters counted. For a script that does not write its vowels, send the Latin spelling the person uses.
year integer, required: Birth year between 100 and 2100. Supports historical figures like Einstein (1879) and Shakespeare (1564).
month integer, required: Birth month (1-12)
day integer, required: Birth day (1-31)

Show all 18 optional fieldsShow fewer optional fields

lang query, string enum: Report language (BCP 47): the labels, headings and readings are written in it. Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. One of en, tr, de, es, hi, pt, fr, ru. Default en.
currentYear integer: Calendar year for the Personal Year. When omitted it is the year of targetDate, or of the current UTC date when targetDate is omitted too. It moves the Personal Year only: the nested personalMonth and maturityStatus.currentAge read targetDate.
targetDate string (date): Date to read the chart on, in YYYY-MM-DD format, in the years 100 to 2100, on or after the birth date. Send the local date of the user for an exact answer: it sets maturityStatus.currentAge and isActive, the Personal Month, and the Personal Year when currentYear is absent. Defaults to today (UTC).
format string enum: Output format: pdf (a print-ready PDF, base64 in the pdf field), html (one self-contained HTML document in the html field) or markdown (CommonMark in the markdown field). One of pdf, html, markdown.
branding object: White-label branding for this report. Every field is optional and nothing is stored: send it with each request.
branding.name string: Business or practitioner name printed on the cover and in the running header of every page.
branding.logo string (uri): HTTPS URL of a PNG, JPEG, WebP or SVG logo under 1 MB, printed on the cover. It is fetched for this report only and never stored.
branding.footer string: Line printed at the foot of every page, such as a disclaimer or a booking note.
branding.website string (uri): Website printed on the cover.
branding.email string (email): Contact email printed on the cover.
branding.colors object: Brand colours. Each one left out keeps the theme colour.
branding.colors.primary string: Headings and table headers, as a six digit hex colour.
branding.colors.accent string: Rules and highlights, as a six digit hex colour.
branding.font string enum: Font pair for headings and text, the same pairs the RoxyAPI UI components take. Left out, the theme typeface is used. One of fraunces-jost, jost, geist, system.
branding.theme string enum: Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used. One of celeste, eucalyptus, kiln, moonlit, practitioner.
page object: Page layout of the PDF.
page.size string enum: Paper size of the PDF. Ignored by html and markdown. One of A4, Letter.
readings boolean: Whether the report carries its written readings. false keeps the charts, tables and key figures and leaves out every interpretation, for a chart-only report at the same cost.

Response

template string, required: The report template rendered.
lang string, required: Language the report is written in.
format string enum, required: Format of the output field present. One of pdf, html, markdown.
title string, required: Report title in the report language, ready for a file name or a heading.
pages integer: Number of PDF pages. Present when format is pdf.
pdf string: The PDF, base64 encoded. Present when format is pdf: decode it and save it as a .pdf file.
html string: The report as one self-contained HTML document. Present when format is html.
markdown string: The report as CommonMark. Present when format is markdown.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /reports/numerology

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.reports.generateNumerologyReport({ body: { fullName: 'John William Smith', year: 1990, month: 7, day: 15 } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.reports.generate_numerology_report(full_name='John William Smith', year=1990, month=7, day=15)

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->reports->generateNumerologyReport(fullName: 'John William Smith', year: 1990, month: 7, day: 15);

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Reports.Numerology.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Reports.GenerateNumerologyReport(ctx, nil, roxyapi.GenerateNumerologyReportJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateNumerologyReportParams, body: &types::NumerologyReportRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.reports().generate_numerology_report(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/reports/numerology" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"John William Smith","year":1990,"month":7,"day":15}'

Edit values

lang

Request body

Example response

{
  "template": "numerology",
  "lang": "en",
  "format": "pdf",
  "title": "Numerology report",
  "pages": 24,
  "pdf": "JVBERi0xLjcK",
  "html": "<!doctype html><html lang=\"en\">",
  "markdown": "# Numerology report"
}

POST /api/v2/reports/tarot

Tarot reading report

Renders the tarot reading report from the same input as its chart, as a white-label document under your name, logo, colours and typeface. Like every template in the reports catalogue, it returns a print-ready PDF, self-contained HTML or Markdown, in the language set by lang.

Request

Show all 19 optional fieldsShow fewer optional fields

lang query, string enum: Report language (BCP 47): the labels, headings and readings are written in it. Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. One of en, tr, de, es, hi, pt, fr, ru. Default en.
spread string enum: Which spread to draw: celtic-cross (ten cards, the default), three-card, love or career, the same spreads the spread routes cast. One of celtic-cross, three-card, love, career.
question string: Optional querent question, printed on the report. Omit for a general reading.
seed string: Optional seed for a reproducible draw: the same seed and spread always produce the same report. Omit for a random draw; the report prints the seed it used.
format string enum: Output format: pdf (a print-ready PDF, base64 in the pdf field), html (one self-contained HTML document in the html field) or markdown (CommonMark in the markdown field). One of pdf, html, markdown.
branding object: White-label branding for this report. Every field is optional and nothing is stored: send it with each request.
branding.name string: Business or practitioner name printed on the cover and in the running header of every page.
branding.logo string (uri): HTTPS URL of a PNG, JPEG, WebP or SVG logo under 1 MB, printed on the cover. It is fetched for this report only and never stored.
branding.footer string: Line printed at the foot of every page, such as a disclaimer or a booking note.
branding.website string (uri): Website printed on the cover.
branding.email string (email): Contact email printed on the cover.
branding.colors object: Brand colours. Each one left out keeps the theme colour.
branding.colors.primary string: Headings and table headers, as a six digit hex colour.
branding.colors.accent string: Rules and highlights, as a six digit hex colour.
branding.font string enum: Font pair for headings and text, the same pairs the RoxyAPI UI components take. Left out, the theme typeface is used. One of fraunces-jost, jost, geist, system.
branding.theme string enum: Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used. One of celeste, eucalyptus, kiln, moonlit, practitioner.
page object: Page layout of the PDF.
page.size string enum: Paper size of the PDF. Ignored by html and markdown. One of A4, Letter.
readings boolean: Whether the report carries its written readings. false keeps the charts, tables and key figures and leaves out every interpretation, for a chart-only report at the same cost.

Response

template string, required: The report template rendered.
lang string, required: Language the report is written in.
format string enum, required: Format of the output field present. One of pdf, html, markdown.
title string, required: Report title in the report language, ready for a file name or a heading.
pages integer: Number of PDF pages. Present when format is pdf.
pdf string: The PDF, base64 encoded. Present when format is pdf: decode it and save it as a .pdf file.
html string: The report as one self-contained HTML document. Present when format is html.
markdown string: The report as CommonMark. Present when format is markdown.

Errors

Status	Meaning
`400`	Validation error. `issues[]` lists every failed field.
`401`	Invalid or missing API key
`405`	Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
`429`	Monthly rate limit exceeded
`500`	Internal server error

POST /reports/tarot

TypeScript

import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.reports.generateTarotReport({ body: { spread: 'celtic-cross', question: 'What should I know about this situation?', seed: 'reading-2f9c1a', format: 'pdf' } })

Install: npm install @roxyapi/sdk

Python

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.reports.generate_tarot_report(spread='celtic-cross', question='What should I know about this situation?', seed='reading-2f9c1a', format='pdf')

Install: pip install roxy-sdk

PHP

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->reports->generateTarotReport(spread: 'celtic-cross', question: 'What should I know about this situation?', seed: 'reading-2f9c1a', format: 'pdf');

Install: composer require roxyapi/sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Reports.Tarot.PostAsync(new() { /* request fields above */ });

Install: dotnet add package RoxyApi.Sdk

import roxyapi "github.com/RoxyAPI/sdk-go"

roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Reports.GenerateTarotReport(ctx, nil, roxyapi.GenerateTarotReportJSONRequestBody{ /* request fields above */ })

Install: go get github.com/RoxyAPI/sdk-go

Rust

use roxyapi::{Roxy, types};

async fn call(roxy: &Roxy, params: &types::GenerateTarotReportParams, body: &types::TarotReportRequest) -> Result<(), roxyapi::Error> {
    let result = roxy.reports().generate_tarot_report(params, body).await?;
    println!("{result:?}");
    Ok(())
}

Install: cargo add roxyapi

cURL

curl -X POST "https://roxyapi.com/api/v2/reports/tarot" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spread":"celtic-cross","question":"What should I know about this situation?","seed":"reading-2f9c1a","format":"pdf"}'

Edit values

lang

Request body

Example response

{
  "template": "tarot",
  "lang": "en",
  "format": "pdf",
  "title": "Tarot reading report",
  "pages": 24,
  "pdf": "JVBERi0xLjcK",
  "html": "<!doctype html><html lang=\"en\">",
  "markdown": "# Tarot reading report"
}