Back to Website

WeSleep API Documentation

Professional sleep intelligence API for healthcare insurance providers in Catalonia and beyond. Our API provides comprehensive sleep data analysis, smart alarm predictions, and actionable health insights.

Overview

The WeSleep API enables healthcare insurance companies to integrate advanced sleep intelligence into their platforms. Our RESTful API provides real-time sleep data processing, predictive analytics, and health insights.

Key Features

  • Real-time sleep data ingestion from wearable devices
  • Smart alarm optimization based on sleep patterns
  • Weekly and monthly health insights
  • Clinical anomaly detection and alerts
  • Ready-to-use frontend dashboard integration

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

  1. Sign up for a WeSleep account
  2. Navigate to the API dashboard
  3. Generate your production API key
  4. Keep your API key secure and never share it publicly

Rate Limits

To ensure optimal performance for all users, we implement rate limiting based on your subscription plan.

Rate Limit Tiers

Plan Requests/Minute Requests/Hour Features
Starter 100 6,000 Basic endpoints
Professional 500 30,000 All endpoints + priority
Enterprise Unlimited Unlimited All endpoints + dedicated support

Error Responses

Rate Limit Exceeded Response:
429 Response
{ "error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later.", "details": { "limit": 100, "window": "60s", "retry_after": 45 } }

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
user_id String Unique identifier for user
timestamp String (ISO 8601) Sleep session end time
duration Number (milliseconds) Total sleep duration in milliseconds
hypnogram Array Sleep phase transitions with timestamps
metrics Object Sleep quality metrics and measurements

Example Request

Request Body
{ "user_id": "user-123", "timestamp": "2024-01-15T07:30:00Z", "duration": 4800000, "hypnogram": [...], "metrics": {...} }

Smart Alarm Prediction

Get the optimal wake-up time for a specific user based on their sleep patterns. The algorithm analyzes 7-night history to find the best wake-up moment within a 30-minute window.

GET /api/v1/alarm/predict/{patient_id}

Query Parameters

Parameter Type Required Description
target_time String (HH:MM) Yes Desired wake-up time

Example Response

Response
{ "patient_id": "user-123", "target_time": "07:30", "optimal_time": "07:18", "confidence_score": 0.87, "window_start": "07:00", "window_end": "07:30" }

Sleep Insights

Get weekly and monthly sleep analysis and engagement summaries for users. Provides motivational insights and progress tracking.

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

Example Response

Weekly Insights
{ "patient_id": "user-123", "period": "weekly", "current_week": {...}, "previous_week": {...}, "trends": {...} }

Dashboard Integration

We provide a ready-to-use frontend dashboard that automatically displays sleep data from your API. No frontend development required - simply integrate with our API and the dashboard will visualize the data for you.

Integration Steps

  1. Send sleep data via POST /api/v1/webhooks/wearable/
  2. Dashboard automatically fetches and displays data
  3. Your users see beautiful sleep analytics immediately