sleeptrack-api

name: sleeptrack-api description: Asleep REST API integration reference. Use when building server-side applications, API clients, webhook handlers, or any backend that interacts with the Asleep sleep tracking platform. Covers authentication, user management, session data retrieval, statistics, and webhook events.

Asleep REST API Reference

Overview

This skill is a language-agnostic REST API reference for the Asleep sleep tracking platform. It documents endpoints, request/response formats, webhook events, and integration best practices without prescribing a specific programming language or framework.

For detailed response field definitions and example payloads, see references/response_schemas.md.

Authentication

All requests require an API key passed via the x-api-key header.

Obtaining an API key:

1. Sign up or log in at https://dashboard.asleep.ai
2. Navigate to the Settings tab
3. Generate an API key for your application

Base URL:

https://api.asleep.ai

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

Common Headers

Response Format

All successful responses follow this envelope structure:

{
  "detail": "success",
  "result": { }
}

Error responses omit the result field:

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

User Management Endpoints

POST /ai/v1/users -- Create User

Creates a new user. The body is optional; include metadata to attach demographic information.

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}}'

Request body (all fields optional):

Response (201 Created): Returns the generated user_id in result.

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

GET /ai/v1/users/{user_id} -- Get User

Retrieves user profile, deletion status, last session info, and metadata.

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

Response (200 OK):

PUT /ai/v1/users/{user_id} -- Update User

Updates user metadata. Send the same metadata object as in Create User.

curl -X PUT https://api.asleep.ai/ai/v1/users/USER_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"height": 180.0, "weight": 75.0}}'

Response (200 OK): Returns the user_id in result.

DELETE /ai/v1/users/{user_id} -- Delete User

Permanently removes a user and all associated sessions and data.

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

Response (204 No Content): Empty body on success.

Session Data Endpoints

GET /data/v3/sessions/{session_id} -- Get Session

Returns the full session object (sleep stages, snoring stages) and the stat object (all computed metrics) for a single session.

curl https://api.asleep.ai/data/v3/sessions/SESSION_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: USER_ID" \
  -H "timezone: America/New_York"

Response (200 OK):

Sleep stages are recorded every 30 seconds: -1 (unknown), 0 (wake), 1 (light), 2 (deep), 3 (REM).

See references/response_schemas.md for the complete field-by-field breakdown of the session and stat objects.

GET /data/v1/sessions -- List Sessions

Returns a paginated list of sessions for a user.

curl "https://api.asleep.ai/data/v1/sessions?date_gte=2024-01-01&date_lte=2024-01-31&order_by=DESC&limit=50" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: USER_ID"

Query parameters:

Response (200 OK): Contains timezone and sleep_session_list array. Each item includes session_id, state, session_start_time, session_end_time, created_timezone, unexpected_end_time, last_received_seq_num, and time_in_bed.

DELETE /ai/v1/sessions/{session_id} -- Delete Session

Permanently removes a session, its uploaded audio, and analysis data.

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"

Response (204 No Content): Empty body on success.

Statistics Endpoint

GET /data/v1/users/{user_id}/average-stats -- Get Average Stats

Returns aggregated sleep metrics over a date range.

curl "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"

Query parameters:

Response (200 OK):

See references/response_schemas.md for the full average_stats field listing.

Webhook Events

Asleep sends HTTP POST requests to your configured callback URL when sleep data events occur. Configure your callback URL via the SDK callbackUrl parameter or through the Asleep Dashboard.

Webhook requests include x-api-key and x-user-id headers for authentication. Always use webhook version V3 for new integrations.

INFERENCE_COMPLETE

Fires every 5-40 minutes during active sleep tracking, providing incremental analysis data.

Payload fields: event, version, user_id, session_id, seq_num, inference_seq_num, sleep_stages, snoring_stages, time_window (start, end).

# Example: simulating a webhook POST to your endpoint
curl -X POST https://your-server.com/webhook \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"event":"INFERENCE_COMPLETE","version":"V3","session_id":"s123","sleep_stages":[1,1,2]}'

SESSION_COMPLETE

Fires once when a session's analysis finishes. The payload mirrors the Get Session response structure, with the addition of top-level event, version, and user_id fields.

Payload fields: event, version, user_id, session_id, session (full object), stat (full object), peculiarities.

See references/response_schemas.md for complete webhook payload schemas with field tables and example JSON.

Webhook Versions

Webhook Authentication

Asleep sends x-api-key and x-user-id as headers on every POST to your callback URL. Verify these headers match expected values before processing the payload.

Webhook Configuration

Webhooks can be configured in two ways:

1. SDK parameter: Pass callbackUrl when initializing the Asleep SDK in your mobile app. The SDK will register the URL with the Asleep platform.
2. Dashboard: Set the webhook URL in the Asleep Dashboard under your application settings.

Your callback endpoint must be a publicly accessible HTTPS URL that responds with a 2xx status code within 30 seconds.

Error Codes

API Versioning

Endpoints use explicit version prefixes:

Version bump policy: Adding new fields to a response does not trigger a version change. Version changes occur only when field names, types, or structural shapes change.

Best Practices

Cache completed sessions. Once a session reaches COMPLETE state, its data is immutable. Store the response locally to avoid redundant API calls.

Use exponential backoff on rate limits. When you receive a 403 rate-limit response, wait with increasing delays (e.g., 1s, 2s, 4s) before retrying. Cap at a reasonable maximum (e.g., 60s).

Ensure webhook idempotency. Track processed session/event IDs to avoid duplicate processing if the same webhook fires more than once.

Respond to webhooks quickly. Return a 2xx status within a few seconds. Offload heavy processing to a background queue to avoid webhook timeouts.

Store API keys securely. Use environment variables or a secret manager. Never commit keys to version control.

Links

• Documentation: https://docs-en.asleep.ai
• Dashboard: https://dashboard.asleep.ai
• LLM-optimized reference: https://docs-en.asleep.ai/llms.txt

Reference Files

This skill includes detailed response schemas and field definitions:

• references/response_schemas.md: Complete field-by-field documentation for all response objects, webhook payloads, enumerations, and example JSON