# 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. Each report states its cost in requests.

## Natal chart report - Branded PDF report API

`POST https://roxyapi.com/api/v2/reports/natal`. MCP tool `post_reports_natal`.

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

- `lang` (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.
- `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.
- `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".
- `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.
- `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).
- `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.
- `branding.theme` (string enum): Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used.
- `page` (object): Page layout of the PDF.
- `page.size` (string enum): Paper size of the PDF. Ignored by html and markdown.
- `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.
- `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.

### Example request

```bash
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"}'
```

### Example response

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

## Synastry report - Branded PDF report API

`POST https://roxyapi.com/api/v2/reports/synastry`. MCP tool `post_reports_synastry`.

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

- `lang` (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.
- `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.
- `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".
- `person1.name` (string): Optional display name for this person. Included in the response for easy identification.
- `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.
- `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".
- `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.
- `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).
- `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.
- `branding.theme` (string enum): Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used.
- `page` (object): Page layout of the PDF.
- `page.size` (string enum): Paper size of the PDF. Ignored by html and markdown.
- `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.
- `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.

### Example request

```bash
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"}}'
```

### Example response

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

## Kundli report - Branded PDF report API

`POST https://roxyapi.com/api/v2/reports/kundli`. MCP tool `post_reports_kundli`.

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

- `lang` (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.
- `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.
- `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.
- `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).
- `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.
- `branding.theme` (string enum): Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used.
- `page` (object): Page layout of the PDF.
- `page.size` (string enum): Paper size of the PDF. Ignored by html and markdown.
- `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.
- `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.

### Example request

```bash
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}'
```

### Example response

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

## Kundli matching report - Branded PDF report API

`POST https://roxyapi.com/api/v2/reports/matchmaking`. MCP tool `post_reports_matchmaking`.

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

- `lang` (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.
- `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.
- `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` (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.
- `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.
- `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).
- `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.
- `branding.theme` (string enum): Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used.
- `page` (object): Page layout of the PDF.
- `page.size` (string enum): Paper size of the PDF. Ignored by html and markdown.
- `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.
- `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.

### Example request

```bash
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}}'
```

### Example response

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

## Yearly forecast report - Branded PDF report API

`POST https://roxyapi.com/api/v2/reports/yearly-forecast`. MCP tool `post_reports_yearly_forecast`.

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

- `lang` (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.
- `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.
- `houseSystem` (string enum): House system for the return chart. placidus is the Western default. whole-sign, equal, and koch are also supported.
- `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).
- `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.
- `branding.theme` (string enum): Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used.
- `page` (object): Page layout of the PDF.
- `page.size` (string enum): Paper size of the PDF. Ignored by html and markdown.
- `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.
- `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.

### Example request

```bash
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"}'
```

### Example response

```json
{
  "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"
}
```

## Human Design report - Branded PDF report API

`POST https://roxyapi.com/api/v2/reports/human-design`. MCP tool `post_reports_human_design`.

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

- `lang` (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.
- `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.
- `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".
- `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).
- `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.
- `branding.theme` (string enum): Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used.
- `page` (object): Page layout of the PDF.
- `page.size` (string enum): Paper size of the PDF. Ignored by html and markdown.
- `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.
- `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.

### Example request

```bash
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"}'
```

### Example response

```json
{
  "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"
}
```

## BaZi report - Branded PDF report API

`POST https://roxyapi.com/api/v2/reports/bazi`. MCP tool `post_reports_bazi`.

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

- `lang` (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.
- `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.
- `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.
- `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.
- `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.
- `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.
- `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.
- `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).
- `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.
- `branding.theme` (string enum): Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used.
- `page` (object): Page layout of the PDF.
- `page.size` (string enum): Paper size of the PDF. Ignored by html and markdown.
- `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.
- `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.

### Example request

```bash
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}'
```

### Example response

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

## Numerology report - Branded PDF report API

`POST https://roxyapi.com/api/v2/reports/numerology`. MCP tool `post_reports_numerology`.

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

- `lang` (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.
- `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)
- `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).
- `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.
- `branding.theme` (string enum): Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used.
- `page` (object): Page layout of the PDF.
- `page.size` (string enum): Paper size of the PDF. Ignored by html and markdown.
- `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.
- `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.

### Example request

```bash
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}'
```

### Example response

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

## Tarot reading report - Branded PDF report API

`POST https://roxyapi.com/api/v2/reports/tarot`. MCP tool `post_reports_tarot`.

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

- `lang` (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.
- `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.
- `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).
- `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.
- `branding.theme` (string enum): Design preset shared with the RoxyAPI UI components: colours, typefaces and spacing. Left out, the neutral default is used.
- `page` (object): Page layout of the PDF.
- `page.size` (string enum): Paper size of the PDF. Ignored by html and markdown.
- `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.
- `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.

### Example request

```bash
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"}'
```

### Example response

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