Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openwearables.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
About this reference

This API Reference covers endpoints for 3rd party integrations - everything you need to manage users, connect wearable providers, and retrieve health data. Internal endpoints (dashboard management, team settings, webhook receivers) are not listed here. For the full API including internal endpoints, use Swagger UI.

Swagger UI (full API)

Interactive API explorer with all endpoints, including internal

OpenAPI JSON

Machine-readable OpenAPI 3.1 specification

​
Overview

The Open Wearables API provides a unified REST interface to access health data from multiple wearable devices and fitness platforms. All endpoints are versioned under /api/v1 and follow RESTful conventions.

​
Base URL

When running locally: 
http://localhost:8000/api/v1
For production deployments, replace with your server URL.

​
Quick Reference

OperationMethodEndpoint
List usersGET/api/v1/users
Create userPOST/api/v1/users
Get userGET/api/v1/users/{user_id}
Get connectionsGET/api/v1/users/{user_id}/connections
Get activity summaryGET/api/v1/users/{user_id}/summaries/activity
Get sleep summaryGET/api/v1/users/{user_id}/summaries/sleep
Get body summaryGET/api/v1/users/{user_id}/summaries/body
Get recovery summaryGET/api/v1/users/{user_id}/summaries/recovery
Get timeseriesGET/api/v1/users/{user_id}/timeseries
Get workoutsGET/api/v1/users/{user_id}/events/workouts
Get sleep sessionsGET/api/v1/users/{user_id}/events/sleep
Get data sourcesGET/api/v1/users/{user_id}/data-sources
Get health scoresGET/api/v1/users/{user_id}/health-scores
List providersGET/api/v1/oauth/providers
OAuth authorizeGET/api/v1/oauth/{provider}/authorize?user_id={user_id}
Sync dataPOST/api/v1/providers/{provider}/users/{user_id}/sync
Historical syncPOST/api/v1/providers/{provider}/users/{user_id}/sync/historical
Get provider workoutsGET/api/v1/providers/{provider}/users/{user_id}/workouts
List event typesGET/api/v1/webhooks/event-types
Register webhook endpointPOST/api/v1/webhooks/endpoints
List webhook endpointsGET/api/v1/webhooks/endpoints
Update webhook endpointPATCH/api/v1/webhooks/endpoints/{endpoint_id}
Delete webhook endpointDELETE/api/v1/webhooks/endpoints/{endpoint_id}
Get endpoint secretGET/api/v1/webhooks/endpoints/{endpoint_id}/secret

​
Authentication

All API endpoints require authentication using API keys. Include your API key in the X-Open-Wearables-API-Key header: 
X-Open-Wearables-API-Key: YOUR_API_KEY
Do not use Bearer token format. The API uses a custom header, not the standard Authorization header.

​
Getting an API Key

  1. Access the Open Wearables Platform at http://localhost:3000
  2. Log in
  3. Navigate to the API Keys section in the Settings tab
  4. Generate a new API key
  5. Copy and securely store the key
Keep your API keys secure. Never commit them to version control or expose them in client-side code.

​
Response Formats

The API uses different response formats depending on the endpoint type:

​
Resource Lists (Users)

{
  "items": [...],
  "total": 50,
  "page": 1,
  "limit": 20,
  "pages": 3,
  "has_next": true,
  "has_prev": false
}

​
Data Endpoints (Timeseries, Workouts, Sleep)

{
  "data": [...],
  "pagination": {
    "next_cursor": "abc123...",
    "previous_cursor": null,
    "has_more": true
  },
  "metadata": {
    "resolution": null,
    "sample_count": 100,
    "start_time": "2025-01-01T00:00:00Z",
    "end_time": "2025-01-31T00:00:00Z"
  }
}

​
Error Response

{
  "detail": "Error message describing what went wrong"
}

​
HTTP Status Codes

  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 204 No Content - Request succeeded, no content to return
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Authentication required or invalid
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error

​
Pagination

The API uses two pagination styles depending on the endpoint:

​
Offset Pagination (Users)

GET /api/v1/users?page=2&limit=50
ParameterDefaultDescription
page1Page number
limit20Items per page (max: 100)

​
Cursor Pagination (Timeseries, Workouts, Sleep)

GET /api/v1/users/{user_id}/timeseries?cursor=abc123&limit=50
ParameterDefaultDescription
cursornullCursor from previous response
limit50Items per page (max: 100)
Use the next_cursor from the response to fetch the next page.

​
Date & Time Parameters

Endpoints that accept date range parameters (start_date, end_date, start_time, end_time) support the following input formats:
FormatExampleNotes
ISO 8601 datetime with timezone2023-11-07T05:31:56ZRecommended
ISO 8601 datetime with offset2023-11-07T06:31:56+01:00
Date-only2023-11-07Normalized to midnight UTC (2023-11-07T00:00:00Z)
Unix timestamp (seconds)1699332716UTC
When a date-only value (e.g. 2023-11-07) is provided as an end date, it is treated as midnight UTC at the start of that day. Depending on the endpoint, this may be extended to include the full day — use an explicit time component (e.g. 2023-11-07T23:59:59Z) to avoid ambiguity.

​
Filtering & Sorting

Many endpoints support filtering and sorting. Check individual endpoint documentation for available options.

​
OpenAPI Specification

The complete OpenAPI specification is available at:
  • Swagger UI: https://api.openwearables.io/docs
  • OpenAPI JSON: https://api.openwearables.io/openapi.json
The OpenAPI specification is auto-generated from the API code and is always the most accurate reference.