6.1 KiB
Asleep API Reference
Official Documentation
- Main Documentation: https://docs-en.asleep.ai
- LLM-Optimized Docs: https://docs-en.asleep.ai/llms.txt
- Dashboard: https://dashboard.asleep.ai
API Authentication
All Asleep API requests require authentication using an API key.
Getting an API Key
- Sign up for the Asleep Dashboard at https://dashboard.asleep.ai
- Navigate to the API key generation section
- Generate your API key for your application
- Store the API key securely (never commit to version control)
Authentication Method
Include the API key in request headers:
X-API-Key: your_api_key_here
Core Concepts
User Management
Each application user must be registered with Asleep before tracking sleep data.
- User ID: Unique identifier for each user (managed by your application)
- User data is associated with sessions and reports
- Users can have multiple sleep tracking sessions
Sleep Sessions
A sleep session represents one tracking period from start to stop.
Session States:
- IDLE: Not tracking
- INITIALIZING: Preparing to track
- INITIALIZED: Ready to track
- TRACKING_STARTED: Active tracking in progress
- TRACKING_STOPPING: Ending tracking session
Key Session Characteristics:
- Minimum tracking time: 5 minutes for valid session
- Real-time data available after sequence 10, then every 10 sequences
- Each session generates a comprehensive sleep report
Sleep Reports
Reports contain detailed analysis of a completed sleep session.
Core Metrics:
- Sleep stages: Wake, Light, Deep, REM
- Sleep efficiency: Percentage of time actually sleeping
- Sleep latency: Time to fall asleep
- Total sleep time
- Time in bed
- Wake after sleep onset (WASO)
- Sleep stage ratios and durations
- Snoring detection and analysis
Statistics
Aggregated sleep metrics across multiple sessions.
Available Statistics:
- Average sleep duration
- Average sleep efficiency
- Sleep stage distribution
- Trends over time periods
Error Codes
Critical Errors (Stop Tracking)
- ERR_MIC_PERMISSION: Microphone access permission denied
- ERR_AUDIO: Microphone in use by another app or hardware issue
- ERR_INVALID_URL: Malformed API endpoint URL
- ERR_COMMON_EXPIRED: API rate limit exceeded or plan expired
- ERR_UPLOAD_FORBIDDEN: Multiple simultaneous tracking attempts with same user ID
- ERR_UPLOAD_NOT_FOUND: Session does not exist or already ended
- ERR_CLOSE_NOT_FOUND: Attempted to close non-existent session
Warning Errors (Continue Tracking)
- ERR_AUDIO_SILENCED: Audio temporarily unavailable but tracking continues
- ERR_AUDIO_UNSILENCED: Audio restored after silence
- ERR_UPLOAD_FAILED: Network issue during upload, will retry
REST API Endpoints
User Management
Create User
POST /users
Body: { "user_id": "string" }
Get User
GET /users/{user_id}
Update User
PUT /users/{user_id}
Body: { /* user properties */ }
Delete User
DELETE /users/{user_id}
Session Management
Get Session
GET /sessions/{session_id}
List Sessions
GET /sessions?user_id={user_id}&from={date}&to={date}
Delete Session
DELETE /sessions/{session_id}
Statistics
Get Average Stats
GET /users/{user_id}/statistics/average?from={date}&to={date}
Webhooks
Asleep supports webhooks for real-time event notifications.
Supported Events:
- Session started
- Session completed
- Report generated
- User created/updated/deleted
Webhook Configuration: Configure webhook URLs in the Asleep Dashboard.
Platform SDKs
Android SDK
- Language: Kotlin
- Minimum SDK: Check latest documentation
- Key Classes: AsleepConfig, SleepTrackingManager
- Architecture: MVVM patterns, Hilt dependency injection
- Permissions Required:
- RECORD_AUDIO (microphone)
- POST_NOTIFICATIONS
- REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
- FOREGROUND_SERVICE
iOS SDK
- Language: Swift
- Minimum iOS Version: Check latest documentation
- Key Classes: AsleepConfig, SleepTrackingManager
- Architecture: Delegate patterns, Combine framework
- Permissions Required:
- Microphone access (NSMicrophoneUsageDescription)
- Notifications
- Background modes
Data Structures
Session
Represents a sleep tracking session with metadata and tracking state information.
Report
Comprehensive sleep analysis including:
- Sleep stages timeline
- Statistical metrics
- Snoring analysis
- Quality indicators
Statistics
Aggregated metrics across multiple sessions for trend analysis.
Best Practices
API Key Security
- Never hardcode API keys in source code
- Use environment variables or secure storage
- Rotate keys periodically
- Monitor usage in Dashboard
User ID Management
- Use consistent user IDs across sessions
- Consider user privacy in ID scheme
- Implement proper user consent flows
Error Handling
- Distinguish between critical errors (stop tracking) and warnings (continue)
- Provide user-friendly error messages
- Implement retry logic for network failures
- Log errors for debugging
Session Management
- Validate minimum tracking time (5 minutes)
- Handle app lifecycle properly (don't lose sessions)
- Implement reconnection logic for interrupted sessions
- Clean up resources when stopping tracking
Performance
- Check real-time data appropriately (after sequence 10, every 10 sequences)
- Cache reports when appropriate
- Batch API requests when possible
- Monitor API rate limits
Common Use Cases
Health & Fitness Apps
Integrate sleep tracking alongside activity tracking for comprehensive health insights.
Healthcare & Wellness
Clinical-grade sleep monitoring for patient care and wellness programs.
Sleep Tech
Dedicated sleep improvement applications with detailed analysis and recommendations.
Smart Home & IoT
Integrate sleep data with smart home automation for optimized sleep environment.
Support & Resources
- Documentation: https://docs-en.asleep.ai
- Dashboard: https://dashboard.asleep.ai
- Email: Contact through dashboard for technical support