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

# Wearable API Quickstart

> Make your first wearable API call in 5 minutes. Covers Docker setup, environment config, and your first authenticated health data request.

## Get started in three steps

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

### Step 1: Set up your environment

<AccordionGroup>
  <Accordion icon="copy" title="Clone the repository">
    Clone the Open Wearables repository to your local machine:

    ```bash theme={null}
    git clone https://github.com/the-momentum/open-wearables.git
    cd open-wearables
    ```
  </Accordion>

  <Accordion icon="gear" title="Configure environment variables">
    Create environment files for both backend and frontend:

    **Backend configuration:**

    ```bash theme={null}
    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:**

    ```bash theme={null}
    cp ./frontend/.env.example ./frontend/.env
    ```

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

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

    <Tip>Default credentials are provided in the `.env.example` files for local development.</Tip>
  </Accordion>
</AccordionGroup>

### Step 2: Start the application

<AccordionGroup>
  <Accordion icon="docker" title="Using Docker (Recommended)">
    The easiest way to get started is with Docker Compose:

    ```bash theme={null}
    docker compose up -d
    ```

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

    ```bash theme={null}
    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](http://localhost:8000)
    * 📚 **Swagger UI**: [http://localhost:8000/docs](http://localhost:8000/docs)
    * 🔐 **Developer Panel**: [http://localhost:3000](http://localhost:3000)

    <Tip>Use `docker compose logs -f` to view logs from all services.</Tip>
  </Accordion>

  <Accordion icon="rectangle-terminal" title="Local development setup">
    For local development without Docker:

    **Backend setup:**

    1. Install dependencies using `uv` (recommended) or `pip`:
       ```bash theme={null}
       cd backend
       uv sync
       ```

    2. Set up PostgreSQL and Redis locally

    3. Run database migrations:
       ```bash theme={null}
       alembic upgrade head
       ```

    4. Start the FastAPI server:
       ```bash theme={null}
       uvicorn app.main:api --reload
       ```

    **Frontend setup:**

    5. Install frontend dependencies using `npm`:
       ```bash theme={null}
       cd frontend
       npm install
       ```

    6. Start the frontend development server:
       ```bash theme={null}
       npm run dev
       ```

    The frontend will be available at [http://localhost:3000](http://localhost:3000)
  </Accordion>
</AccordionGroup>

### Step 3: Make your first API call

<Accordion icon="rocket" title="Test the API">
  Once the application is running, you can test it:

  1. **Check server status**:
     ```bash theme={null}
     curl http://localhost:8000/
     ```
     Should return: `{"message": "Server is running!"}`

  2. **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/](http://localhost:3000/) to log in and generate API keys.

  3. **Seed sample data** (optional):
     If you want test users and sample activity data:
     ```bash theme={null}
     make seed
     ```

  4. **View API documentation**:
     Open [http://localhost:8000/docs](http://localhost:8000/docs) in your browser to explore the interactive Swagger UI.

  5. **Make requests**:
     ```bash theme={null}
     # Use the API key to make authenticated requests
     curl http://localhost:8000/api/v1/users \
       -H "X-Open-Wearables-API-Key: YOUR_API_KEY"
     ```
</Accordion>

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Explore all available API endpoints.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/the-momentum/open-wearables">
    View source code and contribute.
  </Card>
</CardGroup>

<Note>
  **Need help?** Check out our [GitHub Discussions](https://github.com/the-momentum/open-wearables/discussions) or open an issue on GitHub.
</Note>