zhongwei/gh-asleep-ai-sleeptrack-skills-sleeptrack-skills

Fork 0

Files

Zhongwei Li 9faa5d88f3 Initial commit

2025-11-29 17:58:23 +08:00

15 KiB

Raw Blame History

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:

x-api-key: YOUR_API_KEY

Obtain your API key from the Asleep Dashboard.

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:

{
  "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):

{
  "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):

{
  "detail": "success",
  "result": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Example (curl):

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):

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):

{
  "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):

{
  "detail": "user does not exist"
}

Example (curl):

curl -X GET "https://api.asleep.ai/ai/v1/users/USER_ID" \
  -H "x-api-key: YOUR_API_KEY"

Example (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:

{
  "detail": "user_id is invalid"
}

404 Not Found:

{
  "detail": "user does not exist"
}

Example (curl):

curl -X DELETE "https://api.asleep.ai/ai/v1/users/USER_ID" \
  -H "x-api-key: YOUR_API_KEY"

Example (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):

{
  "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:

{
  "detail": "Invalid timezone format"
}

404 Not Found:

{
  "detail": "Session not found"
}

Example (curl):

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):

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):

{
  "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):

{
  "detail": "Invalid timezone"
}

Example (curl):

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):

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:

{
  "detail": "x-user-id is invalid"
}

404 Not Found (User):

{
  "detail": "user does not exist"
}

404 Not Found (Session):

{
  "detail": "session does not exist"
}

Example (curl):

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):

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):

{
  "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:

{
  "detail": "The period should be less than or equal to 100 days"
}

404 Not Found:

{
  "detail": "Unable to find the user of id {user_id}"
}

Example (curl):

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):

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.

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/

15 KiB Raw Blame History

Asleep REST API Reference

Base URL

Authentication

Common Headers

Response Format

Common Error Codes

User Management APIs

[POST] Create User

[GET] Get User

[DELETE] Delete User

Session Management APIs

[GET] Get Session

[GET] List Sessions

[DELETE] Delete Session

Statistics APIs

[GET] Get Average Stats

Rate Limiting

API Versioning

15 KiB

Raw Blame History