260 lines
6.1 KiB
Markdown
260 lines
6.1 KiB
Markdown
# 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
|
|
|
|
1. Sign up for the Asleep Dashboard at https://dashboard.asleep.ai
|
|
2. Navigate to the API key generation section
|
|
3. Generate your API key for your application
|
|
4. 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
|