Initial commit

2025-11-29 17:58:23 +08:00
commit 9faa5d88f3
22 changed files with 9600 additions and 0 deletions
--- a/skills/sleeptrack-be/references/rest_api_reference.md
+++ b/skills/sleeptrack-be/references/rest_api_reference.md
@@ -0,0 +1,725 @@
+# 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/`