Open Wearables API Reference

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.

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

Open the developer portal at http://localhost:3000
Log in
Navigate to Settings → Credentials → API Keys
Generate a new API key
Copy and securely store the key - it is shown only once

The full key is displayed only once, right after you create or rotate it. Open Wearables stores a hash of the key, so it cannot be retrieved later - the portal shows just a short prefix (for example sk-a1b2c3d) to help you tell keys apart. If you lose a key, rotate it from the same section to get a new one.

API keys are shared across the whole deployment. Every developer account can see, rotate, and delete every key, see Credentials.

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

Parameter	Default	Description
`page`	1	Page number
`limit`	20	Items per page (max: 100)

Cursor Pagination (Timeseries, Events, Summaries)

GET /api/v1/users/{user_id}/timeseries?cursor=abc123&limit=50

Parameter	Default	Description
`cursor`	null	Cursor from previous response
`limit`	50	Items per page (max: 1000)

Use the next_cursor from the response to fetch the next page. Health scores page by limit and offset instead, with the same defaults and maximum.

On /timeseries, total_count is returned on the first page only and is null on any page reached by cursor — the count is a full aggregate over the largest table in the system, and a keyset page cannot change it, so keep the value from the first response. A request with a resolution other than raw pages by bucket and never carries a total_count, since counting buckets would require scanning the whole requested range. Cursors are not interchangeable between resolutions or endpoints.

Date & Time Parameters

Endpoints that accept date range parameters (start_date, end_date, start_time, end_time) support the following input formats:

Format	Example	Notes
ISO 8601 datetime with timezone	`2023-11-07T05:31:56Z`	Recommended
ISO 8601 datetime with offset	`2023-11-07T06:31:56+01:00`
Date-only	`2023-11-07`	Start bounds: midnight UTC. End bounds: the whole day
Unix timestamp (seconds)	`1699332716`	UTC

Date-only ranges include both boundary days, so start_date=2023-11-07&end_date=2023-11-07 covers the whole of November 7th. Values with an explicit time component are used exactly as given: end_time=2023-11-07T00:00:00Z stops at midnight and returns nothing from that day.

Filtering & Sorting

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

OpenAPI Specification

This reference is generated from docs/openapi.json, which is exported from the API code on every change, so it always describes the current main branch. Every Open Wearables instance also serves the spec for the exact version it runs:

Swagger UI: https://<your-instance>/docs
OpenAPI JSON: https://<your-instance>/openapi.json

If you self-host an older release, the spec served by your own instance is the accurate reference for it.

Overview

Integration Guides

Authentication

Users

Connections

Providers

Data Sync

Summaries

Timeseries

Events

Health Scores

Data Sources

Meta

Apple Health Import

Mobile SDK

Webhooks

Sync Status

Open Wearables API Reference

About this reference

Swagger UI (full API)

OpenAPI JSON

Overview

Base URL

Authentication

Getting an API Key

Response Formats

Resource Lists (Users)

Data Endpoints (Timeseries, Workouts, Sleep)

Error Response

HTTP Status Codes

Date & Time Parameters

Filtering & Sorting

OpenAPI Specification

​About this reference

Swagger UI (full API)

OpenAPI JSON

​Overview

​Base URL

​Authentication

​Getting an API Key

​Response Formats

​Resource Lists (Users)

​Data Endpoints (Timeseries, Workouts, Sleep)

​Error Response

​HTTP Status Codes

​Pagination

​Offset Pagination (Users)

​Cursor Pagination (Timeseries, Events, Summaries)

​Date & Time Parameters

​Filtering & Sorting

​OpenAPI Specification

About this reference

Overview

Base URL

Authentication

Getting an API Key

Response Formats

Resource Lists (Users)

Data Endpoints (Timeseries, Workouts, Sleep)

Error Response

HTTP Status Codes

Pagination

Offset Pagination (Users)

Cursor Pagination (Timeseries, Events, Summaries)

Date & Time Parameters

Filtering & Sorting

OpenAPI Specification