# Biorhythm API

> The most complete biorhythm API + remote MCP for AI agents and developers. Hosted MCP server, no local setup, connect Claude Code, Cursor, VS Code in seconds. 10 cycle types: 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 day identification, two-person compatibility scoring, phase tracking for dashboards, and seeded daily readings for push notifications. 6 endpoints, 8 languages, sub-millisecond response times, editorial-grade interpretations. Ship a biorhythm feature in hours, not weeks.

Ship a biorhythm feature your users will love. This week.

- Product page: https://roxyapi.com/products/biorhythm-api
- OpenAPI spec: https://roxyapi.com/api/v2/biorhythm/openapi.json
- Remote MCP server: https://roxyapi.com/mcp/biorhythm
- Authentication: `X-API-Key` header on every request
- Pricing: https://roxyapi.com/pricing (all domains included in every plan)

## Stats

- latency: <5ms
- uptime: 99.9%
- endpoints: 6

## Features

- 10 biorhythm cycle types from any birth date: 3 primary (physical 23d, emotional 28d, intellectual 33d), 4 secondary (intuitive 38d, aesthetic 43d, awareness 48d, spiritual 53d), and 3 composite cycles (passion, mastery, wisdom) that standard calculators do not cover
- 8 distinct phase states per cycle: peak, high, rising, critical ascending, critical descending, falling, low, and trough with percentage values from -100 to 100
- Critical day detection across any date range with single, double, and triple severity levels for simultaneous zero crossings across primary cycles
- Two-person compatibility scoring: per-cycle alignment (0-100), overall score, rating label, relationship strengths, challenges, and actionable advice
- 90-day forecasts with daily cycle values, energy ratings (1-10), best and worst day identification, and period-level planning guidance
- Seeded daily readings: same seed and date always return the same reading, built for push notifications, morning briefings, and daily check-in widgets
- 80+ editorial phase interpretations and 25+ combined cycle readings assembled from actual cycle states, not generic filler text
- Pure math, zero external dependencies, deterministic results, sub-millisecond calculations verified against authoritative biorhythm calculators

## Use Cases

- Wellness and self-care apps: daily biorhythm check-ins, energy tracking, recovery scheduling, and personalized wellness calendars based on cycle phases
- Dating and relationship platforms: compatibility scoring between two birth dates, daily relationship sync tracking, and shared cycle insights for couples
- Productivity and scheduling tools: identify peak intellectual days for complex work, flag low-energy days for light tasks, and generate weekly energy forecasts for time blocking
- AI chatbots and virtual assistants: daily biorhythm readings via MCP tool calls, energy level queries, and biorhythm context for wellness coaching conversations
- Fitness and athletic platforms: physical cycle tracking for training periodization, peak coordination days for competition, and recovery phase scheduling
- Content and editorial platforms: daily biorhythm columns for newsletters, personalized push notifications, and engagement widgets based on cycle states

## Endpoints

- `POST /api/v2/biorhythm/reading` Get biorhythm reading - Complete cycle analysis for any date
- `POST /api/v2/biorhythm/forecast` Get biorhythm forecast - Multi-day cycle predictions with best and worst days
- `POST /api/v2/biorhythm/critical-days` Find critical days - Zero crossing detection for any date range
- `POST /api/v2/biorhythm/compatibility` Calculate compatibility - Biorhythm alignment between two people
- `POST /api/v2/biorhythm/phases` Get phase info - Lightweight cycle status for dashboards and widgets
- `POST /api/v2/biorhythm/daily` Get daily biorhythm - Seeded reading for daily check-in features

### Biorhythm (`/biorhythm/`)
- `POST /biorhythm/daily` — Seeded daily biorhythm reading.
- `POST /biorhythm/forecast` — Multi-day range (30 to 90 days) with best, worst, and critical days.
- `POST /biorhythm/compatibility` — Cycle alignment between two people.
- `POST /biorhythm/critical-days` — Zero-crossing days in a 90 to 180 day window.

## Example Response

```
POST /api/v2/biorhythm/daily
```

```json
{
  "date": "2026-05-23",
  "seed": "2026-05-23",
  "energyRating": 9,
  "overallPhase": "high_energy",
  "spotlight": {
    "cycle": "intellectual",
    "value": 95,
    "phase": "peak",
    "message": "Your intellectual cycle is at its peak. Mental clarity, analytical thinking, and problem-solving ability are at maximum. Memory retention is sharp and complex ideas feel manageable."
  },
  "quickRead": {
    "physical": 89,
    "emotional": 43,
    "intellectual": 95
  },
  "dailyMessage": "Your biorhythm for 2026-05-23: Energy rating 9/10 (Peak Performance). Intellectual cycle is peak performance at 95%.",
  "advice": "Tackle your most complex challenges now. Your mind is at its sharpest."
}
```

## SDK Quick Start

```typescript
// npm install @roxyapi/sdk
import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);
const { data, error } = await roxy.biorhythm.getDailyBiorhythm({ body: { birthDate: '1990-06-15' } });
```

```python
# pip install roxy-sdk
import os
from roxy_sdk import create_roxy
roxy = create_roxy(api_key=os.environ["ROXY_API_KEY"])
result = roxy.biorhythm.get_daily_biorhythm(birth_date="1990-06-15")
```

```php
// composer require roxyapi/sdk (PHP 8.2+, built on Saloon)
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->biorhythm->getReading(birthDate: '1990-06-15');
```

Method names come from OpenAPI `operationId` (camelCase in TS and PHP, snake_case in Python). TS returns `{ data, error, response }` — check `error` first. Python raises `RoxyAPIError`; PHP throws `RoxyApiException` (catch and switch on `$e->errorCode`).

## MCP Tool Naming

Each REST endpoint has a matching MCP tool on `https://roxyapi.com/mcp/biorhythm`. Tool name convention is `{http_method_lowercase}_{path_with_slashes_as_underscores_kebab_replaced_with_underscores_braces_stripped}`:

```
POST /biorhythm/reading                       -> post_biorhythm_reading
POST /biorhythm/forecast                      -> post_biorhythm_forecast
POST /biorhythm/critical-days                 -> post_biorhythm_critical_days
```

`tools/list` is free and public (no auth). `tools/call` requires `X-API-Key` (same billing as REST — 1 request per call).

## Field Formats (agent gotchas)

Fields LLMs most often get wrong. Copy the format exactly.

| Field | Format | Good | Bad |
|-------|--------|------|-----|
| `birthDate` (biorhythm) | ISO date string | `"1990-01-15"` | Date object, `"15/01/1990"` |
| `date` | ISO date string | `"1990-01-15"` | `"Jan 15 1990"`, `"15/01/1990"` |
| `seed` (daily endpoints) | Any string | `"user-42"`, email hash | Numbers, objects |
| `person1` / `person2` | Nested object with full birth data | `{ date, time, latitude, longitude, timezone }` | Flat fields |

**Path hygiene:** no trailing slashes on any endpoint.

## Common Mistakes (verified from production)

LLMs frequently produce broken Biorhythm code. These are the correct patterns.

- Forecast and critical-days both use `{ birthDate, startDate?, endDate? }`. Forecast max window is 90 days, critical-days max is 180 days.
- Compatibility body uses nested objects: `{ person1: { birthDate }, person2: { birthDate }, targetDate? }` — NOT flat `person1BirthDate`.
- Daily body is optional `{ seed?, date? }`.

## Domain Gotchas

LLMs hallucinate confidently in this category. These are the specific traps.

- **Seed-based daily endpoints are DETERMINISTIC per (seed, date) pair.** Same seed + same date = same reading. This is by design for push-notification consistency. Do not describe it as "cached" or retry on stale responses.

## Multi-language Support

Append `?lang=` to translated endpoints. Supported on this domain: `en, de, es, fr, hi, pt, ru, tr`. English is the default. The `lang` param is ignored on endpoints that have no translatable text.

## Error Contract

Success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable):

- `validation_error` (400, returns `issues[]` with all field errors at once)
- `api_key_required` (401), `invalid_api_key` (401)
- `subscription_inactive` (403), `subscription_not_found` (404)
- `not_found` (404; PATH-routing 404s carry a fuzzy `suggestion` field)
- `rate_limit_exceeded` (429)
- `internal_error` (500)

Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff.

## Full Reference

For complete request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/biorhythm/openapi.json. Master agent manifest at https://roxyapi.com/llms.txt. Execution playbook at https://roxyapi.com/AGENTS.md.