Biorhythm API reference

Biorhythm API for entertainment and reflection, with 10 model cycle types across 3 primary (physical, emotional, intellectual), 4 secondary (intuitive, aesthetic, awareness, spiritual), and 3 composite (passion, mastery, wisdom). Critical-day detection with severity classification, 90-day forecasts with best and worst days, two-person compatibility scoring, phase tracking for dashboards, and daily readings that hold all day for push notifications. Localized into every language this API ships, deterministic results, and editorial-grade interpretations. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs.

6 endpoints. Product page. Typed SDKs in six languages carry every operation below.

Your API keyKept in this tab only. Without a key, a small daily allowance still answers every request below.

Get biorhythm reading - Complete cycle analysis for any date

POST /api/v2/biorhythm/reading

Calculate a complete biorhythm reading for a given birth date and target date. Returns all 10 cycle values (physical, emotional, intellectual, intuitive, aesthetic, awareness, spiritual, passion, mastery, wisdom), phase detection with 8 distinct states, energy rating (1-10), overall phase assessment, editorial-grade interpretation, actionable advice, and critical day alerts. Perfect for wellness apps, dating platforms, productivity tools, and AI chatbot integrations that need structured biorhythm data.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`birthDate` required	string (date)	Birth date of the person in YYYY-MM-DD format. This is the anchor for all biorhythm cycle calculations.
`targetDate`	string (date)	Date to calculate the reading for in YYYY-MM-DD format. Defaults to today (UTC) if omitted.

curl

curl -X POST "https://roxyapi.com/api/v2/biorhythm/reading" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate":"1990-07-15"}'

Response fields

Field	Type	Description
`birthDate` required	string	Birth date used for this calculation (YYYY-MM-DD).
`targetDate` required	string	Date this reading is for (YYYY-MM-DD).
`daysSinceBirth` required	number	Total days alive from birth date to target date. This is the basis for all cycle calculations.
`cycles` required	object	All 10 biorhythm cycle readings. Keys: physical, emotional, intellectual, intuitive, aesthetic, awareness, spiritual, passion, mastery, wisdom.
`energyRating` required	number	Overall energy score from 1 (deep recovery) to 10 (peak performance), derived from the three primary cycle positions.
`overallPhase` required	string enum	Summary phase across every cycle for the day. One of: high_energy, mixed, recovery, critical.
`interpretation` required	string	Editorial 3-5 sentence reading combining all cycle states into a coherent daily assessment.
`advice` required	string	Actionable 1-2 sentence guidance for the day based on the combined cycle analysis.
`criticalAlerts` required	array of object	Critical day alerts. Present only when one or more primary cycles are at or near zero crossing.
`criticalAlerts[].cycle` required	string enum	Which cycle is at or near zero crossing.
`criticalAlerts[].type` required	string enum	Alert type. One of: zero_crossing. Raised once for the whole critical band, when the cycle sits within 9 points of zero in either direction.
`criticalAlerts[].direction` required	string enum	Whether the cycle is rising through zero (ascending) or falling through zero (descending).
`criticalAlerts[].advisory` required	string	Specific advisory text for this critical alert.

Example response

{
  "birthDate": "1990-07-15",
  "targetDate": "2026-04-10",
  "daysSinceBirth": 13049,
  "cycles": {
    "physical": {
      "value": -14,
      "rawValue": -0.1362,
      "phase": "falling",
      "phaseLabel": "Falling",
      "dayInCycle": 13,
      "daysUntilPeak": 17,
      "daysUntilTrough": 5,
      "daysUntilCritical": 11,
      "trend": "falling",
      "interpretation": "Your physical energy is declining. Endurance and strength are decreasing, and fatigue may set in more quickly than usual. This is a natural part of the cycle."
    }
  },
  "energyRating": 7,
  "overallPhase": "high_energy",
  "interpretation": "Your physical energy is strong and building. Endurance and coordination are above average. Good conditions for exercise, physical projects, and activities requiring sustained effort. Your emotional energy is also elevated, supporting your overall capacity.",
  "advice": "Tackle physically demanding tasks while your energy remains elevated.",
  "criticalAlerts": [
    {
      "cycle": "physical",
      "type": "zero_crossing",
      "direction": "ascending",
      "advisory": "physical cycle crosses zero while ascending. Transition from recovery to active phase."
    }
  ]
}

Get biorhythm forecast - Multi-day cycle predictions with best and worst days

POST /api/v2/biorhythm/forecast

Generate a biorhythm forecast for a date range up to 90 days. Returns daily cycle values for physical, emotional, intellectual, and intuitive cycles, daily energy ratings, critical day identification, and a summary with best day, worst day, average energy, and period-level guidance. Ideal for wellness apps, productivity planners, scheduling tools, and calendar integrations that need forward-looking biorhythm data.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`birthDate` required	string (date)	Birth date of the person in YYYY-MM-DD format.
`startDate`	string (date)	Start date of the forecast range in YYYY-MM-DD format. Defaults to today (UTC).
`endDate`	string (date)	End date of the forecast range in YYYY-MM-DD format. Defaults to startDate + 30 days. Maximum range: 90 days.

curl

curl -X POST "https://roxyapi.com/api/v2/biorhythm/forecast" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate":"1990-07-15"}'

Response fields

Field	Type	Description
`birthDate` required	string	Birth date used for this calculation.
`startDate` required	string	First day of the forecast range.
`endDate` required	string	Last day of the forecast range.
`totalDays` required	number	Number of days in the forecast range.
`summary` required	object
`summary.bestDay` required	string	Date with the highest average primary cycle values in the range. Best day for demanding activities.
`summary.worstDay` required	string	Date with the lowest average primary cycle values in the range. Best scheduled as a rest day.
`summary.criticalDayCount` required	number	Total number of days where at least one primary cycle crosses zero in the range.
`summary.averageEnergy` required	number	Average energy rating (1-10) across the entire forecast period.
`summary.periodAdvice` required	string	Overview guidance for the entire forecast period based on average energy and cycle patterns.
`days` required	array of object	Array of daily readings, one per day in the forecast range.
`days[].date` required	string	Date of this daily reading (YYYY-MM-DD).
`days[].daysSinceBirth` required	number	Days from birth date to this date.
`days[].physical` required	number	Physical cycle value (-100 to 100).

Show all fieldsShow fewer fields

Field	Type	Description
`days[].emotional` required	number	Emotional cycle value (-100 to 100).
`days[].intellectual` required	number	Intellectual cycle value (-100 to 100).
`days[].intuitive` required	number	Intuitive cycle value (-100 to 100).
`days[].energyRating` required	number	Energy rating for this day (1-10).
`days[].isCritical` required	boolean	True if any primary cycle crosses zero on this day.
`days[].criticalCycles` required	array of string	Which primary cycles are critical on this day. Empty array if none.

Example response

{
  "birthDate": "1990-07-15",
  "startDate": "2026-04-01",
  "endDate": "2026-04-30",
  "totalDays": 30,
  "summary": {
    "bestDay": "2026-04-14",
    "worstDay": "2026-04-07",
    "criticalDayCount": 4,
    "averageEnergy": 6,
    "periodAdvice": "This period has a mix of energy levels. Plan demanding work around the best days and schedule lighter activity during the troughs."
  },
  "days": [
    {
      "date": "2026-04-01",
      "daysSinceBirth": 13040,
      "physical": 45,
      "emotional": -30,
      "intellectual": 72,
      "intuitive": 18,
      "energyRating": 6,
      "isCritical": false,
      "criticalCycles": []
    }
  ]
}

Find critical days - Zero crossing detection for any date range

POST /api/v2/biorhythm/critical-days

Find all critical days (zero crossings) within a date range up to 180 days. Returns each critical day with cycle name, period, direction (ascending or descending), severity (single, double, or triple), and advisory text. Highlights rare double critical days where two primary cycles cross zero simultaneously and extremely rare triple critical days where all three primary cycles cross zero on the same date. Ideal for calendar integrations, push notification systems, alert engines, and wellness scheduling tools.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`birthDate` required	string (date)	Birth date of the person in YYYY-MM-DD format.
`startDate`	string (date)	Start date of the search range in YYYY-MM-DD format. Defaults to today (UTC).
`endDate`	string (date)	End date of the search range in YYYY-MM-DD format. Defaults to startDate + 90 days. Maximum range: 180 days.

curl

curl -X POST "https://roxyapi.com/api/v2/biorhythm/critical-days" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate":"1990-07-15"}'

Response fields

Field	Type	Description
`birthDate` required	string	Birth date used for this calculation.
`startDate` required	string	Start of the search range.
`endDate` required	string	End of the search range.
`totalCriticalDays` required	number	Total count of critical day events in the range. A double critical day counts as two events.
`criticalDays` required	array of object	All critical day events in the range, sorted by date.
`criticalDays[].date` required	string	Date of the zero crossing (YYYY-MM-DD).
`criticalDays[].cycle` required	string enum	Which primary cycle crosses zero on this date. One of: physical, emotional, intellectual. Only the three primary cycles are scanned; the secondary and composite cycles are not.
`criticalDays[].period` required	number	Cycle period in days.
`criticalDays[].direction` required	string enum	Whether the cycle is rising through zero (ascending) or falling through zero (descending).
`criticalDays[].severity` required	string enum	How many primary cycles are critical on this date. One of: single, double, triple.
`criticalDays[].advisory` required	string	Advisory text explaining the significance of this critical day and recommended precautions.
`doubleCriticalDays` required	array of string	Dates where 2 or more primary cycles cross zero simultaneously. These are particularly significant days requiring extra caution.
`tripleCriticalDay` required	stringnull	Date where all 3 primary cycles cross zero simultaneously. Extremely rare event. Null if none found in range.

Example response

{
  "birthDate": "1990-07-15",
  "startDate": "2026-04-01",
  "endDate": "2026-06-30",
  "totalCriticalDays": 12,
  "criticalDays": [
    {
      "date": "2026-04-03",
      "cycle": "physical",
      "period": 23,
      "direction": "ascending",
      "severity": "single",
      "advisory": "Physical cycle crosses zero while descending. Transition from active to recovery phase."
    }
  ],
  "doubleCriticalDays": [
    "2026-05-12"
  ],
  "tripleCriticalDay": null
}

Calculate compatibility - Biorhythm alignment between two people

POST /api/v2/biorhythm/compatibility

Calculate biorhythm compatibility between two people by overlaying their cycle profiles on a target date. Returns per-cycle alignment scores (0-100) for physical, emotional, and intellectual cycles, an overall compatibility score, relationship rating, strengths, challenges, practical advice, and a daily sync snapshot showing the absolute difference in each primary cycle. Perfect for dating apps, relationship platforms, team-building tools, and couples coaching applications.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`person1` required	object
`person1.birthDate` required	string (date)	Birth date of person 1 in YYYY-MM-DD format.
`person2` required	object
`person2.birthDate` required	string (date)	Birth date of person 2 in YYYY-MM-DD format.
`targetDate`	string (date)	Date to evaluate compatibility on in YYYY-MM-DD format. Defaults to today (UTC). Compatibility varies by day since biorhythm cycles are continuous.

curl

curl -X POST "https://roxyapi.com/api/v2/biorhythm/compatibility" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person1":{"birthDate":"1990-07-15"},"person2":{"birthDate":"1992-03-22"}}'

Response fields

Field	Type	Description
`person1` required	object
`person1.birthDate` required	string	Birth date of person 1.
`person2` required	object
`person2.birthDate` required	string	Birth date of person 2.
`targetDate` required	string	Date this compatibility was calculated for.
`overallScore` required	number	Overall compatibility score from 0 (fully opposed) to 100 (perfectly synchronized).
`rating` required	string	Compatibility rating label. One of: Highly Aligned, Well Aligned, Moderately Aligned, Misaligned, Opposed.
`cycles` required	object	Per-cycle compatibility analysis for physical, emotional, and intellectual cycles.
`strengths` required	array of string	Relationship strengths based on the compatibility profile.
`challenges` required	array of string	Potential relationship challenges to be aware of.
`advice` required	string	Practical relationship guidance based on the combined cycle analysis.
`dailySync` required	object
`dailySync.physicalDiff` required	number	Absolute difference in physical cycle values (0-200). Lower = more aligned.
`dailySync.emotionalDiff` required	number	Absolute difference in emotional cycle values (0-200). Lower = more aligned.

Show all fieldsShow fewer fields

Field	Type	Description
`dailySync.intellectualDiff` required	number	Absolute difference in intellectual cycle values (0-200). Lower = more aligned.

Example response

{
  "person1": {
    "birthDate": "1990-07-15"
  },
  "person2": {
    "birthDate": "1992-03-22"
  },
  "targetDate": "2026-04-10",
  "overallScore": 72,
  "rating": "Well Aligned",
  "cycles": {
    "physical": {
      "person1Value": -14,
      "person2Value": -100,
      "difference": 86,
      "alignment": 57,
      "phase": "complementary",
      "description": "Physical energy levels complement each other well. Minor differences in pace create healthy balance."
    }
  },
  "strengths": [
    "Good overall energy match with healthy variation",
    "Complementary differences prevent stagnation"
  ],
  "challenges": [
    "One cycle may be out of sync, requiring awareness",
    "Minor timing differences in energy peaks and valleys"
  ],
  "advice": "Your cycles are well matched today. Lean into the aligned areas and be patient with the one dimension that may differ. Small adjustments keep your connection smooth.",
  "dailySync": {
    "physicalDiff": 19,
    "emotionalDiff": 45,
    "intellectualDiff": 12
  }
}

Try it

lang

Request bodyJSON, as the example above shows it.

Not sent

Get phase info - Lightweight cycle status for dashboards and widgets

POST /api/v2/biorhythm/phases

Get current phase information for all 10 biorhythm cycles without the full interpretation payload. Returns value, phase name, phase label, day position within cycle, cycle period, days until next critical crossing, and short-term trend for each cycle. Includes a compact summary string. Designed as a lightweight endpoint for dashboards, widgets, status bars, and quick-check interfaces that need biorhythm phase data without editorial text.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`birthDate` required	string (date)	Birth date of the person in YYYY-MM-DD format.
`targetDate`	string (date)	Date to get phase information for in YYYY-MM-DD format. Defaults to today (UTC).

curl

curl -X POST "https://roxyapi.com/api/v2/biorhythm/phases" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate":"1990-07-15"}'

Response fields

Field	Type	Description
`birthDate` required	string	Birth date used for this calculation.
`targetDate` required	string	Date this phase info is for.
`daysSinceBirth` required	number	Total days alive from birth date to target date.
`phases` required	object	Phase information for all 10 cycles keyed by cycle ID.
`summary` required	string	Quick overview string summarizing the current state of all cycles.

Example response

{
  "birthDate": "1990-07-15",
  "targetDate": "2026-04-10",
  "daysSinceBirth": 13049,
  "phases": {
    "physical": {
      "value": -14,
      "phase": "falling",
      "phaseLabel": "Falling",
      "dayInCycle": 13,
      "totalDays": 23,
      "daysUntilCritical": 11,
      "trend": "falling"
    }
  },
  "summary": "3 cycles rising, 2 at peak, 1 critical"
}

Get daily biorhythm - Seeded reading for daily check-in features

POST /api/v2/biorhythm/daily

Get a daily biorhythm reading with seeded randomness for consistent "biorhythm of the day" features. Same seed and same date always produce the same reading, perfect for daily push notifications, morning briefings, and wellness app check-ins. Returns energy rating, overall phase, a spotlight on one featured cycle, quick-read values for all three primary cycles, a daily message, and actionable advice. The spotlight cycle is deterministically selected by the seed, creating variety across users while maintaining consistency for each individual.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`seed`	string	Optional seed for reproducible readings. Same seed + same date = same reading every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings.
`date`	string (date)	Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones.

curl

curl -X POST "https://roxyapi.com/api/v2/biorhythm/daily" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed":"user123","date":"2026-03-06"}'

Response fields

Field	Type	Description
`date` required	string	Date this daily reading is for (YYYY-MM-DD, UTC).
`seed` required	string	Computed seed used for this reading. Same seed always produces the same reading.
`energyRating` required	number	Overall energy score from 1 to 10.
`overallPhase` required	string enum	Summary phase across every cycle for the day. One of: high_energy, mixed, recovery, critical.
`spotlight` required	object
`spotlight.cycle` required	string enum	Which primary cycle is featured as the daily spotlight. One of: physical, emotional, intellectual.
`spotlight.value` required	number	Current value of the spotlight cycle (-100 to 100).
`spotlight.phase` required	string enum	Current phase of the spotlight cycle.
`spotlight.message` required	string	Personalized message about the spotlight cycle and what it means for today.
`quickRead` required	object
`quickRead.physical` required	number	Physical cycle value (-100 to 100).
`quickRead.emotional` required	number	Emotional cycle value (-100 to 100).
`quickRead.intellectual` required	number	Intellectual cycle value (-100 to 100).
`dailyMessage` required	string	Concise daily biorhythm message combining energy rating and spotlight cycle.

Show all fieldsShow fewer fields

Field	Type	Description
`advice` required	string	Actionable 1-2 sentence guidance for the day.

Example response

{
  "date": "2026-04-10",
  "seed": "user123-2026-04-10",
  "energyRating": 7,
  "overallPhase": "high_energy",
  "spotlight": {
    "cycle": "emotional",
    "value": 72,
    "phase": "high",
    "message": "Your emotional cycle is elevated and positive. Mood is stable and upbeat, and you feel naturally connected to others. Creative ideas come more easily and social interactions feel rewarding."
  },
  "quickRead": {
    "physical": 45,
    "emotional": 72,
    "intellectual": -30
  },
  "dailyMessage": "Your biorhythm for 2026-01-28: Energy rating 8/10 (High). Emotional cycle is high energy at 72%.",
  "advice": "Lean into collaborative projects and relationship building."
}