WhenPeak API

WhenPeak has two access levels.

No key needed: public prediction: POST /api/v1/predict is open. Stateless, no account required.

API key: authenticated endpoints: All personalised endpoints (/ingest/*, /performance/*, /chronotype) require a key sent in the header:

X-WhenPeak-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxx

Key registration is handled in the developer dashboard. Create a free account at whenpeak.com/dashboard.html. Your pk_live key is issued once on signup (Free tier: 1,000 calls/month).

Good:   {"sleep_time":"23:00","wake_time":"07:00","sleep_quality":"good"}
Avoid:  {"sleep_time":"23:00","wake_time":"07:00","sleep_quality":"good",
         "exercise_yesterday":null,"waso_minutes":null}

curl https://api.whenpeak.com/api/v1/auth/verify \
  -H "X-WhenPeak-API-Key: pk_live_..."

Returns {"valid": true, "user_id": "..."}. Costs 1 call against your quota.

If you're building an app where multiple end-users each need their own performance profile, you don't need a separate API key per user. Your developer key authenticates the account; you route each call to the right end-user with a second header.

Step 1: provision your end-users once:

curl -X POST https://api.whenpeak.com/api/v1/users \
  -H "X-WhenPeak-API-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"label": "alice@yourapp.com"}'

{
  "user_id": "a1b2c3...",
  "label": "alice@yourapp.com",
  "created": 888">true
}

Store the user_id in your app. It's the stable identifier for that end-user's sleep and performance history.

Step 2: route every data call to the right user:

curl -X POST https://api.whenpeak.com/api/v1/ingest/sleep \
  -H "X-WhenPeak-API-Key: pk_live_..." \
  -H "X-WhenPeak-User-ID: a1b2c3..." \
  -H "Content-Type: application/json" \
  -d '{...}'

Each end-user's data is fully isolated. All calls count against your developer quota. Management endpoints (provision / list / delete users) do not count against your quota.

Each key has a monthly call quota by tier. Resets on the first of each calendar month (UTC).

The public /api/v1/predict, the usage check endpoint, and all user management endpoints (POST/GET/DELETE /api/v1/users) do not count against your quota.

curl https://api.whenpeak.com/api/v1/auth/usage \
  -H "X-WhenPeak-API-Key: pk_live_..."

{
  "tier": "free",
  "used": 412,
  "limit": 1000,
  "remaining": 588,
  "period": "2026-06"
}

Authenticated endpoints return 429 Too Many Requests:

{
  "detail": "Monthly quota exceeded for the 'free' tier (1,000 calls/month).
             Upgrade at https://whenpeak.com/#pricing."
}

Upgrade on the Pricing page or email hello@whenpeak.com.

Auth Endpoints

User Management Endpoints

These endpoints let you provision and manage end-users under your developer account. Require X-WhenPeak-API-Key. Do not count against your quota.

Provision an isolated end-user. Idempotent. Provisioning the same label twice returns the existing user (created: false) rather than erroring.

Returns: user_id, label, created (true/false).

Prediction Endpoints

Stateless prediction from self-reported data. No authentication required.

Optional fields must be omitted entirely when not provided: do not send as null.

{
  "summary": {
    "average_day": "Tuesday",
    "best_day": "Wednesday",
    "worst_day": "Sunday"
  },
  "forecast": [
    {
      "day": "2026-06-11",
      "dps": 74,
      "curve": [...],
      "peak_1": { "time": "10:00" },
      "peak_2": { "time": "16:00" },
      "dip": { "time": "14:00" },
      "projected_sleep_hours": 7.5,
      "confidence": "high"
    }
  ]
}

The model run in reverse. Prediction answers "given my behaviour, what's my curve?"; suggestion answers "given a target, what behaviour gets me there?": it works backward from a future target to tonight's actions.

Requires an API key (X-WhenPeak-API-Key). Uses the caller's stored sleep history, and is multi-user aware via the X-WhenPeak-User-ID header. Counts as 1 call against your quota.

With few or no synced nights it still returns a plan, labelled with a population_baseline confidence that matures to calibrating and then personalized as sleep history accumulates.

The body has a required target plus optional aggressiveness and constraints.

target is one of three shapes, selected by kind:

aggressiveness (string, optional): "minimal" (default: one gentle nudge, favours keeping your current rhythm) or "full" (travellers / hard deadlines; permits larger daily shifts).

constraints (object, optional):

curl -X POST https://api.whenpeak.com/api/v1/performance/suggest \
  -H "X-WhenPeak-API-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target": {"kind": "point", "date": "2026-07-16", "time": "14:00"}}'

{
  "shape": "point",
  "target": { "date": "2026-07-16", "window": "14:00", "centre": "14:00" },
  "feasibility": {
    "achievable": 888">true,
    "runway_days": 13,
    "limit_reason": 888">null,
    "headline": "There's a clear plan to have you sharp across 14:00. Projected capacity ~80.8/100."
  },
  "confidence": {
    "label": "personalized",
    "nights_of_data": 14,
    "consistency_sd_min": 0.0,
    "note": "Personalised to your measured circadian phase and sleep pattern."
  },
  "current_state": {
    "estimated_chronotype": "Third Bird",
    "estimated_peak": "10:41",
    "typical_wake": "07:00"
  },
  "plan": {
    "summary": "Your rhythm already lines up well with 14:00. The plan is to arrive rested: clear sleep debt over the next 13 nights and protect the night before.",
    "nights": [
      { "date": "2026-07-04", "target_wake": "07:00", "target_bed": "23:15", "target_sleep_hours": 7.75, "focus": "clear sleep debt" },
      { "date": "2026-07-16", "target_wake": "07:00", "target_bed": "23:15", "target_sleep_hours": 7.75, "focus": "protect the night before" }
    ],
    "event_day": {
      "date": "2026-07-16",
      "target_wake": "07:00",
      "projected_peak": "10:00",
      "projected_capacity_at_target": 80.8,
      "projected_window_floor": 888">null,
      "framing": "This puts your projected capacity around 80.8/100 across 14:00: odds in your favour, not a guarantee."
    }
  },
  "tonight": {
    "action": "one_gentle_nudge",
    "detail": "Aim for lights-out around 23:15 tonight to start clearing sleep debt. Just one small step."
  },
  "guardrails": {
    "health_floor_respected": 888">true,
    "min_sleep_hours_prescribed": 7.0,
    "claims_basis": "internal_dps",
    "style": "pull_not_push"
  },
  "disclaimer": "WhenPeak suggestions raise the odds your best hours land where you need them. They are not medical advice and never ask you to cut sleep."
}

All score values (dps, peak value, dip value) are floats. Typing them as int will cause a validation error on real data, e.g. dps: 87.8, not 87.

Available now as a GPT. Users ask in plain English; WhenPeak predicts their peak.

MCP server deployed. Remote integration rolling out.

OpenAPI spec available for any tool-calling LLM:

Tool definitions for Claude and OpenAI function calling are available in the GitHub repo.