Wearable API Quickstart

Get started in three steps

Get Open Wearables running locally and start integrating wearable device data.

Step 1: Set up your environment

Clone the repository

Clone the Open Wearables repository to your local machine:

git clone https://github.com/the-momentum/open-wearables.git
cd open-wearables

Configure environment variables

Create environment files for both backend and frontend:Backend configuration:

cp ./backend/config/.env.example ./backend/config/.env

Edit ./backend/config/.env with your configuration. You’ll need to set up:

Database credentials
Redis/Celery broker settings
OAuth credentials for wearable providers (Garmin, Fitbit, etc.)
Secret keys for authentication

Frontend configuration:

cp ./frontend/.env.example ./frontend/.env

Edit ./frontend/.env with your frontend configuration:

VITE_API_URL - Backend API URL (default: http://localhost:8000)

Default credentials are provided in the .env.example files for local development.

Outgoing webhooks are disabled by default. Set OUTGOING_WEBHOOKS_ENABLED=true to enable real-time event delivery — see the webhooks guide.

Step 2: Start the application

Using Docker (Recommended)

The easiest way to get started is with Docker Compose:

docker compose up -d

For development with hot-reloading, use the --watch flag:

docker compose watch

The --watch flag enables automatic file synchronization and service restarts:

Backend: Automatically syncs code changes and restarts services on file updates
Frontend: Hot-reloads on source file changes
Migrations: Restarts backend when migration files change
Dependencies: Rebuilds containers when package files change

This will start all required services:

PostgreSQL database
Redis
FastAPI backend
Celery worker
Celery beat (scheduler)
Frontend development server

Once started, access:

🌐 API: http://localhost:8000
📚 Swagger UI: http://localhost:8000/docs
🔐 Developer Panel: http://localhost:3000

Use docker compose logs -f to view logs from all services.

Local development setup

For local development without Docker:Backend setup:

Install dependencies using uv (recommended) or pip:
cd backend uv sync
Set up PostgreSQL and Redis locally
Run database migrations:
alembic upgrade head
Start the FastAPI server:
uvicorn app.main:api --reload

Frontend setup:

Install frontend dependencies using npm:
cd frontend npm install
Start the frontend development server:
npm run dev

The frontend will be available at http://localhost:3000

Step 3: Make your first API call

Test the API

Once the application is running, you can test it:

Check server status:
curl http://localhost:8000/
Should return: {"message": "Server is running!"}
Create an API key: An admin account is automatically created on startup using the ADMIN_EMAIL and ADMIN_PASSWORD environment variables (defaults: admin@admin.com / your-secure-password). Use the admin panel at http://localhost:3000/ to log in and generate API keys.
Seed sample data (optional): If you want test users and sample activity data:
make seed
View API documentation: Open http://localhost:8000/docs in your browser to explore the interactive Swagger UI.

Make requests:

# Use the API key to make authenticated requests
curl http://localhost:8000/api/v1/users \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Next steps

API Reference

Explore all available API endpoints.

GitHub

View source code and contribute.

Need help? Check out our GitHub Discussions or open an issue on GitHub.

Getting started

Architecture

Health Scores

Providers

Open Wearables Mobile App

Sync SDK

MCP Server

Developer Guides

Data Migrations

Configuration

Deployment

Support

Get started in three steps

Step 1: Set up your environment

Step 2: Start the application

Step 3: Make your first API call

Next steps

API Reference

GitHub

​Get started in three steps

​Step 1: Set up your environment

​Step 2: Start the application

​Step 3: Make your first API call

​Next steps

API Reference

GitHub

Get started in three steps

Step 1: Set up your environment

Step 2: Start the application

Step 3: Make your first API call

Next steps