Initial commit
This commit is contained in:
Zhongwei Li
259
skills/sleeptrack-foundation/references/asleep_api_reference.md
Normal file
259
skills/sleeptrack-foundation/references/asleep_api_reference.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user