726 lines
15 KiB
Markdown
726 lines
15 KiB
Markdown
# Asleep REST API Reference
|
|
|
|
This reference provides comprehensive documentation for the Asleep REST API endpoints.
|
|
|
|
## Base URL
|
|
|
|
```
|
|
https://api.asleep.ai
|
|
```
|
|
|
|
## Authentication
|
|
|
|
All API requests require authentication via the `x-api-key` header:
|
|
|
|
```http
|
|
x-api-key: YOUR_API_KEY
|
|
```
|
|
|
|
Obtain your API key from the [Asleep Dashboard](https://dashboard.asleep.ai).
|
|
|
|
## Common Headers
|
|
|
|
| Header | Type | Required | Description |
|
|
|--------|------|----------|-------------|
|
|
| x-api-key | String | Yes | API authentication key |
|
|
| x-user-id | String | Conditional | Required for session operations |
|
|
| timezone | String | No | Response timezone (default: UTC) |
|
|
|
|
## Response Format
|
|
|
|
All responses follow this structure:
|
|
|
|
```json
|
|
{
|
|
"detail": "message about the result",
|
|
"result": { /* response data */ }
|
|
}
|
|
```
|
|
|
|
## Common Error Codes
|
|
|
|
| Status | Error | Description |
|
|
|--------|-------|-------------|
|
|
| 401 | Unauthorized | API Key missing or invalid |
|
|
| 403 | Plan expired | Subscription period ended |
|
|
| 403 | Rate limit exceeded | Request quota temporarily exceeded |
|
|
| 403 | Quota exceeded | Total usage limit surpassed |
|
|
| 404 | Not Found | Resource doesn't exist |
|
|
|
|
---
|
|
|
|
## User Management APIs
|
|
|
|
### [POST] Create User
|
|
|
|
Creates a new user for sleep tracking.
|
|
|
|
**Endpoint:**
|
|
```
|
|
POST https://api.asleep.ai/ai/v1/users
|
|
```
|
|
|
|
**Headers:**
|
|
```
|
|
x-api-key: YOUR_API_KEY
|
|
```
|
|
|
|
**Request Body (Optional):**
|
|
```json
|
|
{
|
|
"metadata": {
|
|
"birth_year": 1990,
|
|
"birth_month": 5,
|
|
"birth_day": 15,
|
|
"gender": "male",
|
|
"height": 175.5,
|
|
"weight": 70.0
|
|
}
|
|
}
|
|
```
|
|
|
|
**Metadata Fields:**
|
|
- `birth_year` (Integer): User's birth year
|
|
- `birth_month` (Integer): User's birth month (1-12)
|
|
- `birth_day` (Integer): User's birth day (1-31)
|
|
- `gender` (String): One of: `male`, `female`, `non_binary`, `other`, `prefer_not_to_say`
|
|
- `height` (Float): Height in cm (0-300)
|
|
- `weight` (Float): Weight in kg (0-1000)
|
|
|
|
**Response (201 Created):**
|
|
```json
|
|
{
|
|
"detail": "success",
|
|
"result": {
|
|
"user_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Example (curl):**
|
|
```bash
|
|
curl -X POST "https://api.asleep.ai/ai/v1/users" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"metadata": {
|
|
"birth_year": 1990,
|
|
"gender": "male",
|
|
"height": 175.5,
|
|
"weight": 70.0
|
|
}
|
|
}'
|
|
```
|
|
|
|
**Example (Python):**
|
|
```python
|
|
import requests
|
|
|
|
response = requests.post(
|
|
"https://api.asleep.ai/ai/v1/users",
|
|
headers={"x-api-key": "YOUR_API_KEY"},
|
|
json={
|
|
"metadata": {
|
|
"birth_year": 1990,
|
|
"gender": "male",
|
|
"height": 175.5,
|
|
"weight": 70.0
|
|
}
|
|
}
|
|
)
|
|
user_id = response.json()["result"]["user_id"]
|
|
```
|
|
|
|
---
|
|
|
|
### [GET] Get User
|
|
|
|
Retrieves user information and last session data.
|
|
|
|
**Endpoint:**
|
|
```
|
|
GET https://api.asleep.ai/ai/v1/users/{user_id}
|
|
```
|
|
|
|
**Headers:**
|
|
```
|
|
x-api-key: YOUR_API_KEY
|
|
```
|
|
|
|
**Path Parameters:**
|
|
- `user_id` (String): User identifier
|
|
|
|
**Response (200 OK):**
|
|
```json
|
|
{
|
|
"detail": "success",
|
|
"result": {
|
|
"user_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"to_be_deleted": false,
|
|
"last_session_info": {
|
|
"session_id": "abc123",
|
|
"state": "COMPLETE",
|
|
"session_start_time": "2024-01-20T22:00:00+00:00",
|
|
"session_end_time": "2024-01-21T06:30:00+00:00"
|
|
},
|
|
"metadata": {
|
|
"birth_year": 1990,
|
|
"birth_month": 5,
|
|
"birth_day": 15,
|
|
"gender": "male",
|
|
"height": 175.5,
|
|
"weight": 70.0
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Session States:**
|
|
- `OPEN`: Session in progress, audio uploads available
|
|
- `CLOSED`: Session terminated, analysis in progress
|
|
- `COMPLETE`: All analysis completed
|
|
|
|
**Error Response (404):**
|
|
```json
|
|
{
|
|
"detail": "user does not exist"
|
|
}
|
|
```
|
|
|
|
**Example (curl):**
|
|
```bash
|
|
curl -X GET "https://api.asleep.ai/ai/v1/users/USER_ID" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
```
|
|
|
|
**Example (Python):**
|
|
```python
|
|
import requests
|
|
|
|
response = requests.get(
|
|
f"https://api.asleep.ai/ai/v1/users/{user_id}",
|
|
headers={"x-api-key": "YOUR_API_KEY"}
|
|
)
|
|
user_data = response.json()["result"]
|
|
```
|
|
|
|
---
|
|
|
|
### [DELETE] Delete User
|
|
|
|
Permanently removes a user and all associated data.
|
|
|
|
**Endpoint:**
|
|
```
|
|
DELETE https://api.asleep.ai/ai/v1/users/{user_id}
|
|
```
|
|
|
|
**Headers:**
|
|
```
|
|
x-api-key: YOUR_API_KEY
|
|
```
|
|
|
|
**Path Parameters:**
|
|
- `user_id` (String): User identifier
|
|
|
|
**Response (204 No Content):**
|
|
User information successfully deleted.
|
|
|
|
**Error Responses:**
|
|
|
|
401 Unauthorized:
|
|
```json
|
|
{
|
|
"detail": "user_id is invalid"
|
|
}
|
|
```
|
|
|
|
404 Not Found:
|
|
```json
|
|
{
|
|
"detail": "user does not exist"
|
|
}
|
|
```
|
|
|
|
**Example (curl):**
|
|
```bash
|
|
curl -X DELETE "https://api.asleep.ai/ai/v1/users/USER_ID" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
```
|
|
|
|
**Example (Python):**
|
|
```python
|
|
import requests
|
|
|
|
response = requests.delete(
|
|
f"https://api.asleep.ai/ai/v1/users/{user_id}",
|
|
headers={"x-api-key": "YOUR_API_KEY"}
|
|
)
|
|
# 204 No Content on success
|
|
```
|
|
|
|
---
|
|
|
|
## Session Management APIs
|
|
|
|
### [GET] Get Session
|
|
|
|
Retrieves comprehensive sleep analysis data for a specific session.
|
|
|
|
**Endpoint:**
|
|
```
|
|
GET https://api.asleep.ai/data/v3/sessions/{session_id}
|
|
```
|
|
|
|
**Headers:**
|
|
```
|
|
x-api-key: YOUR_API_KEY
|
|
x-user-id: USER_ID
|
|
timezone: Asia/Seoul # Optional, defaults to UTC
|
|
```
|
|
|
|
**Path Parameters:**
|
|
- `session_id` (String): Session identifier
|
|
|
|
**Query Parameters:**
|
|
None
|
|
|
|
**Response (200 OK):**
|
|
```json
|
|
{
|
|
"detail": "success",
|
|
"result": {
|
|
"timezone": "UTC",
|
|
"peculiarities": [],
|
|
"missing_data_ratio": 0.0,
|
|
"session": {
|
|
"id": "session123",
|
|
"state": "COMPLETE",
|
|
"start_time": "2024-01-20T22:00:00+00:00",
|
|
"end_time": "2024-01-21T06:30:00+00:00",
|
|
"sleep_stages": [0, 0, 1, 1, 2, 3, 2, 1, 0],
|
|
"snoring_stages": [0, 0, 0, 1, 1, 0, 0, 0, 0]
|
|
},
|
|
"stat": {
|
|
"sleep_time": "06:30:00",
|
|
"sleep_index": 85.5,
|
|
"sleep_latency": 900,
|
|
"time_in_bed": 30600,
|
|
"time_in_sleep": 27000,
|
|
"time_in_light": 13500,
|
|
"time_in_deep": 6750,
|
|
"time_in_rem": 6750,
|
|
"sleep_efficiency": 88.24,
|
|
"waso_count": 2,
|
|
"longest_waso": 300,
|
|
"sleep_cycle": [
|
|
{
|
|
"order": 1,
|
|
"start_time": "2024-01-20T22:15:00+00:00",
|
|
"end_time": "2024-01-21T01:30:00+00:00"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Sleep Stages Values:**
|
|
- `-1`: Unknown/No data
|
|
- `0`: Wake
|
|
- `1`: Light sleep
|
|
- `2`: Deep sleep
|
|
- `3`: REM sleep
|
|
|
|
**Snoring Stages Values:**
|
|
- `0`: No snoring
|
|
- `1`: Snoring detected
|
|
|
|
**Peculiarities:**
|
|
- `IN_PROGRESS`: Session still being analyzed
|
|
- `NEVER_SLEPT`: No sleep detected in session
|
|
- `TOO_SHORT_FOR_ANALYSIS`: Session duration < 5 minutes
|
|
|
|
**Error Responses:**
|
|
|
|
400 Bad Request:
|
|
```json
|
|
{
|
|
"detail": "Invalid timezone format"
|
|
}
|
|
```
|
|
|
|
404 Not Found:
|
|
```json
|
|
{
|
|
"detail": "Session not found"
|
|
}
|
|
```
|
|
|
|
**Example (curl):**
|
|
```bash
|
|
curl -X GET "https://api.asleep.ai/data/v3/sessions/SESSION_ID" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "x-user-id: USER_ID" \
|
|
-H "timezone: UTC"
|
|
```
|
|
|
|
**Example (Python):**
|
|
```python
|
|
import requests
|
|
|
|
response = requests.get(
|
|
f"https://api.asleep.ai/data/v3/sessions/{session_id}",
|
|
headers={
|
|
"x-api-key": "YOUR_API_KEY",
|
|
"x-user-id": user_id,
|
|
"timezone": "UTC"
|
|
}
|
|
)
|
|
session_data = response.json()["result"]
|
|
```
|
|
|
|
---
|
|
|
|
### [GET] List Sessions
|
|
|
|
Retrieves multiple sessions with filtering and pagination.
|
|
|
|
**Endpoint:**
|
|
```
|
|
GET https://api.asleep.ai/data/v1/sessions
|
|
```
|
|
|
|
**Headers:**
|
|
```
|
|
x-api-key: YOUR_API_KEY
|
|
x-user-id: USER_ID
|
|
timezone: UTC # Optional
|
|
```
|
|
|
|
**Query Parameters:**
|
|
| Parameter | Type | Required | Default | Description |
|
|
|-----------|------|----------|---------|-------------|
|
|
| date_gte | String (YYYY-MM-DD) | No | - | Sessions on or after this date |
|
|
| date_lte | String (YYYY-MM-DD) | No | - | Sessions on or before this date |
|
|
| order_by | String (ASC/DESC) | No | DESC | Sort direction by start time |
|
|
| offset | Integer | No | 0 | Number of records to skip |
|
|
| limit | Integer (0-100) | No | 20 | Maximum records per request |
|
|
|
|
**Response (200 OK):**
|
|
```json
|
|
{
|
|
"detail": "success",
|
|
"result": {
|
|
"timezone": "UTC",
|
|
"sleep_session_list": [
|
|
{
|
|
"session_id": "session123",
|
|
"state": "COMPLETE",
|
|
"session_start_time": "2024-01-20T22:00:00+00:00",
|
|
"session_end_time": "2024-01-21T06:30:00+00:00",
|
|
"created_timezone": "UTC",
|
|
"unexpected_end_time": null,
|
|
"last_received_seq_num": 156,
|
|
"time_in_bed": 30600
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
**Error Response (400):**
|
|
```json
|
|
{
|
|
"detail": "Invalid timezone"
|
|
}
|
|
```
|
|
|
|
**Example (curl):**
|
|
```bash
|
|
curl -X GET "https://api.asleep.ai/data/v1/sessions?date_gte=2024-01-01&limit=10" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "x-user-id: USER_ID"
|
|
```
|
|
|
|
**Example (Python):**
|
|
```python
|
|
import requests
|
|
|
|
response = requests.get(
|
|
"https://api.asleep.ai/data/v1/sessions",
|
|
headers={
|
|
"x-api-key": "YOUR_API_KEY",
|
|
"x-user-id": user_id
|
|
},
|
|
params={
|
|
"date_gte": "2024-01-01",
|
|
"date_lte": "2024-01-31",
|
|
"limit": 50,
|
|
"order_by": "DESC"
|
|
}
|
|
)
|
|
sessions = response.json()["result"]["sleep_session_list"]
|
|
```
|
|
|
|
---
|
|
|
|
### [DELETE] Delete Session
|
|
|
|
Permanently removes a session and all associated data.
|
|
|
|
**Endpoint:**
|
|
```
|
|
DELETE https://api.asleep.ai/ai/v1/sessions/{session_id}
|
|
```
|
|
|
|
**Headers:**
|
|
```
|
|
x-api-key: YOUR_API_KEY
|
|
x-user-id: USER_ID
|
|
```
|
|
|
|
**Path Parameters:**
|
|
- `session_id` (String): Session identifier
|
|
|
|
**Response (204 No Content):**
|
|
Session, uploaded audio, and analysis data successfully deleted.
|
|
|
|
**Error Responses:**
|
|
|
|
401 Unauthorized:
|
|
```json
|
|
{
|
|
"detail": "x-user-id is invalid"
|
|
}
|
|
```
|
|
|
|
404 Not Found (User):
|
|
```json
|
|
{
|
|
"detail": "user does not exist"
|
|
}
|
|
```
|
|
|
|
404 Not Found (Session):
|
|
```json
|
|
{
|
|
"detail": "session does not exist"
|
|
}
|
|
```
|
|
|
|
**Example (curl):**
|
|
```bash
|
|
curl -X DELETE "https://api.asleep.ai/ai/v1/sessions/SESSION_ID" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "x-user-id: USER_ID"
|
|
```
|
|
|
|
**Example (Python):**
|
|
```python
|
|
import requests
|
|
|
|
response = requests.delete(
|
|
f"https://api.asleep.ai/ai/v1/sessions/{session_id}",
|
|
headers={
|
|
"x-api-key": "YOUR_API_KEY",
|
|
"x-user-id": user_id
|
|
}
|
|
)
|
|
# 204 No Content on success
|
|
```
|
|
|
|
---
|
|
|
|
## Statistics APIs
|
|
|
|
### [GET] Get Average Stats
|
|
|
|
Retrieves average sleep metrics over a specified time period (up to 100 days).
|
|
|
|
**Endpoint:**
|
|
```
|
|
GET https://api.asleep.ai/data/v1/users/{user_id}/average-stats
|
|
```
|
|
|
|
**Headers:**
|
|
```
|
|
x-api-key: YOUR_API_KEY
|
|
timezone: UTC # Optional
|
|
```
|
|
|
|
**Path Parameters:**
|
|
- `user_id` (String): User identifier
|
|
|
|
**Query Parameters:**
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| start_date | String (YYYY-MM-DD) | Yes | Period start date |
|
|
| end_date | String (YYYY-MM-DD) | Yes | Period end date (max 100 days from start) |
|
|
|
|
**Response (200 OK):**
|
|
```json
|
|
{
|
|
"detail": "success",
|
|
"result": {
|
|
"period": {
|
|
"start_date": "2024-01-01",
|
|
"end_date": "2024-01-31",
|
|
"days": 31
|
|
},
|
|
"peculiarities": [],
|
|
"average_stats": {
|
|
"start_time": "22:30:00",
|
|
"end_time": "06:45:00",
|
|
"sleep_time": "07:15:00",
|
|
"wake_time": "06:45:00",
|
|
"sleep_latency": 900,
|
|
"wakeup_latency": 300,
|
|
"time_in_bed": 30600,
|
|
"time_in_sleep_period": 29700,
|
|
"time_in_sleep": 26100,
|
|
"time_in_wake": 3600,
|
|
"time_in_light": 13050,
|
|
"time_in_deep": 6525,
|
|
"time_in_rem": 6525,
|
|
"time_in_snoring": 1800,
|
|
"time_in_no_snoring": 24300,
|
|
"sleep_efficiency": 85.29,
|
|
"wake_ratio": 0.12,
|
|
"sleep_ratio": 0.88,
|
|
"light_ratio": 0.50,
|
|
"deep_ratio": 0.25,
|
|
"rem_ratio": 0.25,
|
|
"snoring_ratio": 0.07,
|
|
"no_snoring_ratio": 0.93,
|
|
"waso_count": 2.5,
|
|
"longest_waso": 420,
|
|
"sleep_cycle_count": 4.2,
|
|
"snoring_count": 15.3
|
|
},
|
|
"never_slept_sessions": [],
|
|
"slept_sessions": [
|
|
{
|
|
"session_id": "session123",
|
|
"session_start_time": "2024-01-20T22:00:00+00:00"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
**Metrics Explanation:**
|
|
|
|
**Time Metrics** (HH:MM:SS format or seconds):
|
|
- `start_time`: Average bedtime
|
|
- `end_time`: Average wake time
|
|
- `sleep_time`: Average time of falling asleep
|
|
- `wake_time`: Average time of waking up
|
|
- `sleep_latency`: Average time to fall asleep (seconds)
|
|
- `wakeup_latency`: Average time from wake to getting up (seconds)
|
|
- `time_in_bed`: Average total time in bed (seconds)
|
|
- `time_in_sleep_period`: Average time from sleep onset to wake (seconds)
|
|
- `time_in_sleep`: Average actual sleep time (seconds)
|
|
- `time_in_wake`: Average wake time during sleep period (seconds)
|
|
|
|
**Sleep Stage Durations** (seconds):
|
|
- `time_in_light`: Average light sleep duration
|
|
- `time_in_deep`: Average deep sleep duration
|
|
- `time_in_rem`: Average REM sleep duration
|
|
|
|
**Snoring Metrics** (seconds):
|
|
- `time_in_snoring`: Average snoring duration
|
|
- `time_in_no_snoring`: Average non-snoring duration
|
|
|
|
**Ratio Metrics** (0-1 decimal):
|
|
- `sleep_efficiency`: Sleep time / Time in bed
|
|
- `wake_ratio`, `sleep_ratio`: Wake/sleep proportions
|
|
- `light_ratio`, `deep_ratio`, `rem_ratio`: Sleep stage proportions
|
|
- `snoring_ratio`, `no_snoring_ratio`: Snoring proportions
|
|
|
|
**Event Counts**:
|
|
- `waso_count`: Average wake after sleep onset episodes
|
|
- `longest_waso`: Average longest wake episode (seconds)
|
|
- `sleep_cycle_count`: Average number of sleep cycles
|
|
- `snoring_count`: Average snoring episodes
|
|
|
|
**Peculiarities:**
|
|
- `NO_BREATHING_STABILITY`: Inconsistent breathing data
|
|
|
|
**Error Responses:**
|
|
|
|
400 Bad Request:
|
|
```json
|
|
{
|
|
"detail": "The period should be less than or equal to 100 days"
|
|
}
|
|
```
|
|
|
|
404 Not Found:
|
|
```json
|
|
{
|
|
"detail": "Unable to find the user of id {user_id}"
|
|
}
|
|
```
|
|
|
|
**Example (curl):**
|
|
```bash
|
|
curl -X GET "https://api.asleep.ai/data/v1/users/USER_ID/average-stats?start_date=2024-01-01&end_date=2024-01-31" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "timezone: UTC"
|
|
```
|
|
|
|
**Example (Python):**
|
|
```python
|
|
import requests
|
|
|
|
response = requests.get(
|
|
f"https://api.asleep.ai/data/v1/users/{user_id}/average-stats",
|
|
headers={
|
|
"x-api-key": "YOUR_API_KEY",
|
|
"timezone": "UTC"
|
|
},
|
|
params={
|
|
"start_date": "2024-01-01",
|
|
"end_date": "2024-01-31"
|
|
}
|
|
)
|
|
stats = response.json()["result"]
|
|
```
|
|
|
|
---
|
|
|
|
## Rate Limiting
|
|
|
|
The Asleep API implements rate limiting to ensure fair usage:
|
|
|
|
- **Rate Limit Exceeded (403)**: Temporary quota exceeded
|
|
- **Quota Exceeded (403)**: Total usage limit reached
|
|
- **Plan Expired (403)**: Subscription period ended
|
|
|
|
Monitor your usage in the [Asleep Dashboard](https://dashboard.asleep.ai).
|
|
|
|
**Best Practices:**
|
|
- Implement exponential backoff for retries
|
|
- Cache responses when appropriate
|
|
- Batch requests when possible
|
|
- Monitor usage proactively
|
|
|
|
---
|
|
|
|
## API Versioning
|
|
|
|
The Asleep API uses versioned endpoints (e.g., `/v1/`, `/v3/`). Version upgrades occur when:
|
|
|
|
- Renaming response object fields
|
|
- Modifying data types or enum values
|
|
- Restructuring response objects
|
|
- Introducing breaking changes
|
|
|
|
Non-breaking changes (like adding new fields) don't trigger version upgrades.
|
|
|
|
**Current Versions:**
|
|
- User Management: `/ai/v1/`
|
|
- Session Data: `/data/v3/` (Get Session), `/data/v1/` (List Sessions)
|
|
- Statistics: `/data/v1/`
|