API Documentation

Overview

The WeSleep API enables platforms across health insurance, sports, corporate wellness, and consumer wellness apps to integrate advanced sleep intelligence. Our RESTful API provides real-time sleep data processing, predictive analytics, and actionable insights — you build the experience, we power the intelligence behind it.

Key Features

Sleep data ingestion from wearable devices
Smart alarm optimization based on personalized sleep patterns
Weekly and monthly sleep insights
Sustained pattern alerts — no diagnosis, purely informational
Optional ready-to-use dashboard, or build your own frontend

Quick Start

sk-ws-prod-1234567890abcdef

Authentication

All API requests require authentication using your API key. Include your API key in the Authorization header as shown below.

Request Headers

Authentication Headers

Authorization: Bearer your-api-key
Content-Type: application/json

Getting Your API Key

API keys are currently issued manually per client during onboarding. Reach out to our team to get provisioned with your production API key.

Contact us at bernat@wesleep.pro to start onboarding
We'll provision a dedicated API key for your organization
Keep your API key secure and never share it publicly or commit it to version control

Unauthorized Requests

Requests without a valid API key are rejected before reaching any business logic.

401 Response

{ "detail": "Missing or invalid Authorization header. Expected: Bearer <api_key>" }

Rate Limits

🚧Coming Soon!🚧

Wearable Data Ingestion

Receive raw sleep data from wearable devices and store it for analysis. This endpoint accepts sleep session data including hypnogram, metrics, and timestamps.

POST /api/v1/webhooks/wearable/

Request Body Parameters

Parameter	Type	Description
`record_id`	UUID	Unique identifier for the sleep record
`modified_at`	String (ISO 8601)	Last modification timestamp
`start_at_timestamp`	String (ISO 8601)	Sleep period start
`end_at_timestamp`	String (ISO 8601)	Sleep period end
`duration`	Number (milliseconds)	Total sleep duration in milliseconds
`metrics`	Object	Health metrics payload
`provider_source`	String	The source of the sleep data (e.g., device name, app name)
`provider_slug`	String	The slugified version of the provider source: e.g., "fitbit", "apple-watch"

Example Request

Request Body

{ "record_id": "0134ff3c-3f60-8c46-8e4e-c0dd218c4e3a",
"modified_at": "2025-04-30T12:00:26Z",
"start_at_timestamp": "2025-04-28T17:30:00Z",
"end_at_timestamp": "2025-04-29T03:34:00Z",
"duration": 36240000,
"metrics": { "heartrate": 56, "sleep_duration": 25920000 },
"provider_source": "apple_healthkit_sleep_aggregation",
"provider_slug": "apple" }

Smart Alarm Prediction

Get the optimal wake-up time based on sleep pattern analysis, within a 30-minute window before your target time.

POST /api/v1/sleep/smart-alarm

Request Body Parameters

EX: `time_interval (6:00/6:30) suggested_trigger (6:22)`

Parameter	Type	Required	Description
`sleep_record_id`	UUID	Yes	The ID of the sleep record to analyze
`target_time`	String ISO 8601	Yes	Desired wake-up time

Example Response

Response

{ "suggested_time": "2026-02-12T06:45:00Z",
"confidence": 0.9,
"reasoning": "Optimal wake-up window identified based on recent sleep cycle patterns.",
"quality_score": 91.0,
"anomalies": [] }

Sleep Insights

Get weekly and monthly sleep pattern analysis for a specific patient, including trend comparisons and sustained pattern alerts.

GET /api/v1/insights/weekly/{patient_id}

Example Response

Weekly Insights

{ "patient_id": "e9f7e4d0-2e3e-4ebf-b77a-18011e5897fa",
"previous_week": { "hrv_avg": 55.0, "deep_minutes_avg": 90.0, "efficiency_avg": 0.85 },
"current_week": { "hrv_avg": 58.0, "deep_minutes_avg": 95.0, "efficiency_avg": 0.88 },
"hrv_trend_percent": 5.5,
"deep_trend_percent": 5.6,
"efficiency_trend_percent": 3.5,
"daily": [ { "date": "2026-02-05", "hrv": 57.2, "deep_minutes": 92.1, "efficiency": 0.86 }, /* ...13 more days */ ],
"weekly_recap": "Your sleep quality improved this week, with better HRV and more consistent deep sleep." }

Monthly Insights

Analyzes a 30-day window to detect sustained changes in sleep patterns. Returns an alert only when a meaningful shift is detected — no fixed threshold, evaluated holistically.

⚠️ Requires at least 30 days of sleep history for this patient. Returns 400 if there isn't enough data yet.

GET /api/v1/insights/monthly/{patient_id}

Example Response

Monthly Insights

{ "status": "ok",
"alert": null }

Dashboard Integration

Use our ready-to-use dashboard to visualize sleep data out of the box — or integrate the API directly into your own product with full design control. Your choice.

Option A — Use our dashboard

Send sleep data via POST /api/v1/webhooks/wearable/
Dashboard automatically fetches and displays data
Your users see sleep analytics immediately, no frontend work needed

Option B — Build your own

Send sleep data via POST /api/v1/webhooks/wearable/
Call smart-alarm, insights/weekly, and insights/monthly directly from your app
Render the data with your own UI and branding

Code Examples

Full request examples for the most common integration flows, in multiple languages.

Sending Sleep Data

cURL

curl -X POST https://api.wesleep.pro/api/v1/webhooks/wearable/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": "0134ff3c-3f60-8c46-8e4e-c0dd218c4e3a",
    "modified_at": "2025-04-30T12:00:26Z",
    "start_at_timestamp": "2025-04-28T17:30:00Z",
    "end_at_timestamp": "2025-04-29T03:34:00Z",
    "duration": 36240000,
    "metrics": {"heartrate": 56, "sleep_duration": 25920000},
    "provider_source": "apple_healthkit_sleep_aggregation",
    "provider_slug": "apple"
  }'

JavaScript

const response = await fetch('https://api.wesleep.pro/api/v1/webhooks/wearable/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    record_id: '0134ff3c-3f60-8c46-8e4e-c0dd218c4e3a',
    modified_at: '2025-04-30T12:00:26Z',
    start_at_timestamp: '2025-04-28T17:30:00Z',
    end_at_timestamp: '2025-04-29T03:34:00Z',
    duration: 36240000,
    metrics: { heartrate: 56, sleep_duration: 25920000 },
    provider_source: 'apple_healthkit_sleep_aggregation',
    provider_slug: 'apple'
  })
});

Python

import requests

response = requests.post(
  "https://api.wesleep.pro/api/v1/webhooks/wearable/",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={
    "record_id": "0134ff3c-3f60-8c46-8e4e-c0dd218c4e3a",
    "modified_at": "2025-04-30T12:00:26Z",
    "start_at_timestamp": "2025-04-28T17:30:00Z",
    "end_at_timestamp": "2025-04-29T03:34:00Z",
    "duration": 36240000,
    "metrics": {"heartrate": 56, "sleep_duration": 25920000},
    "provider_source": "apple_healthkit_sleep_aggregation",
    "provider_slug": "apple"
  }
)

Requesting a Smart Alarm Prediction

JavaScript

const response = await fetch('https://api.wesleep.pro/api/v1/sleep/smart-alarm', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sleep_record_id: '0134ff3c-3f60-8c46-8e4e-c0dd218c4e3a',
    target_time: '2026-02-12T07:00:00Z'
  })
});

const alarm = await response.json();

Recommended Wake-up Sounds

The Smart Alarm endpoint tells you when to wake the user — the sound itself is up to your app. If you want to move beyond harsh default phone alarms, here's what the science says makes a good wake-up sound, and a few starting points.

What the research suggests

Factor	Recommendation
Frequency	Around 500 Hz tends to be more effective at rousing the brain than very high or very low tones
Tempo	100–120 BPM, a steady rhythm rather than an erratic one
Volume	Gradual increase rather than an immediate loud blast — reduces the stress response on waking
Structure	Melodic, hummable tunes reduce grogginess (sleep inertia) more than flat, repetitive beeping

Example tracks that fit these criteria

Good Vibrations

The Beach Boys

Lovely Day

Bill Withers

On Top of the World

Imagine Dragons

Wake Up

Arcade Fire

Viva La Vida

Coldplay

It's recommended to rotate sounds every few weeks. The brain learns to filter out a repeated alarm sound over time, even a good one.

For inspiration, you can point users to a curated playlist — for example on Spotify — but keep in mind this is for reference only: actually triggering playback with a gradual volume ramp at the exact suggested_time needs to be built into your app's native alarm/notification logic, not driven by a streaming link.

Error Handling

The WeSleep API uses standard HTTP status codes. Error responses include a detail field describing what went wrong.

Status	Meaning
400	Bad request — e.g. insufficient sleep history for the requested insight
401	Missing or invalid API key
404	The requested resource (e.g. sleep record) was not found
429	Rate limit exceeded
500	Unexpected server error

Example: Insufficient Data (400)

400 Response

{ "detail": "Datos insuficientes para el análisis" }

Example: Record Not Found (404)

404 Response

{ "detail": "Sleep record not found" }

Support

Need help integrating WeSleep? Reach out and we'll get back to you.

Email: bernat@wesleep.pro

Response time: "In less than 24 hours"

WeSleep API Documentation

Overview

Key Features

Quick Start

Authentication

Request Headers

Getting Your API Key

Unauthorized Requests

Rate Limits

🚧Coming Soon!🚧

Wearable Data Ingestion

Request Body Parameters

Example Request

Smart Alarm Prediction

Request Body Parameters

EX: time_interval (6:00/6:30) suggested_trigger (6:22)

Example Response

Sleep Insights

Example Response

Monthly Insights

Example Response

Dashboard Integration

Option A — Use our dashboard

Option B — Build your own

Code Examples

Sending Sleep Data

Requesting a Smart Alarm Prediction

Recommended Wake-up Sounds

What the research suggests

Example tracks that fit these criteria

Error Handling

Example: Insufficient Data (400)

Example: Record Not Found (404)

Support

EX: `time_interval (6:00/6:30) suggested_trigger (6:22)`