Skip to main content

​
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.

​
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.