# Tara API Endpoint Reference

Complete reference for all Tara API endpoints with request/response examples.

## Table of Contents

- [Health & Status](#health--status)
- [Authentication](#authentication)
- [Users](#users)
- [Meditations](#meditations)
- [Sessions](#sessions)
- [Favorites](#favorites)
- [History](#history)
- [Progress](#progress)
- [Subscriptions](#subscriptions)

---

## Health & Status

### Health Check

Check if the API is running.

```http
GET /health
```

**Response (200 OK):**

```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 86400,
  "version": "1.0.0"
}
```

### Readiness Check

Check if the API is ready to serve requests (database connected, etc.).

```http
GET /ready
```

**Response (200 OK):**

```json
{
  "status": "ready",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "storage": "ok"
  }
}
```

**Response (503 Service Unavailable):**

```json
{
  "status": "not_ready",
  "checks": {
    "database": "ok",
    "redis": "failed",
    "storage": "ok"
  }
}
```

### Version Information

Get API version and build information.

```http
GET /version
```

**Response (200 OK):**

```json
{
  "version": "1.0.0",
  "build": "sha-abc1234",
  "environment": "production",
  "node": "22.0.0"
}
```

---

## Authentication

### Register

Create a new user account.

```http
POST /api/v1/auth/register
Content-Type: application/json
```

**Request Body:**

| Field            | Type    | Required | Description                              |
| ---------------- | ------- | -------- | ---------------------------------------- |
| email            | string  | Yes      | User email address                       |
| password         | string  | Yes      | Password (min 8 chars, complex)          |
| name             | string  | Yes      | Display name                             |
| acceptedTerms    | boolean | Yes      | Terms acceptance (must be true)          |
| marketingConsent | boolean | No       | Marketing email consent                  |
| timezone         | string  | No       | User timezone (e.g., "America/New_York") |
| locale           | string  | No       | Preferred locale (e.g., "en-US")         |

**Example Request:**

```json
{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "name": "John Doe",
  "acceptedTerms": true,
  "marketingConsent": false,
  "timezone": "America/New_York"
}
```

**Response (201 Created):**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123def456",
      "email": "user@example.com",
      "name": "John Doe",
      "emailVerified": false,
      "timezone": "America/New_York",
      "locale": "en-US",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}
```

### Login

Authenticate with email and password.

```http
POST /api/v1/auth/login
Content-Type: application/json
```

**Request Body:**

| Field      | Type   | Required | Description                 |
| ---------- | ------ | -------- | --------------------------- |
| email      | string | Yes      | User email address          |
| password   | string | Yes      | User password               |
| deviceId   | string | No       | Unique device identifier    |
| deviceName | string | No       | Human-readable device name  |
| platform   | string | No       | Platform: ios, android, web |

**Example Request:**

```json
{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "deviceId": "550e8400-e29b-41d4-a716-446655440000",
  "deviceName": "iPhone 15 Pro",
  "platform": "ios"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123def456",
      "email": "user@example.com",
      "name": "John Doe",
      "emailVerified": true,
      "avatarUrl": "https://cdn.tara.app/avatars/usr_abc123.jpg",
      "subscription": {
        "tier": "premium",
        "status": "active",
        "expiresAt": "2024-12-15T00:00:00.000Z",
        "autoRenew": true
      },
      "streak": {
        "current": 15,
        "longest": 45,
        "lastActivityDate": "2024-01-14"
      },
      "settings": {
        "notifications": true,
        "dailyReminder": "08:00",
        "preferredDuration": 10
      }
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}
```

### Logout

Revoke tokens and logout.

```http
POST /api/v1/auth/logout
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request Body:**

| Field        | Type    | Required | Description             |
| ------------ | ------- | -------- | ----------------------- |
| refreshToken | string  | No       | Refresh token to revoke |
| allDevices   | boolean | No       | Logout from all devices |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "Successfully logged out",
    "devicesLoggedOut": 1
  }
}
```

### Refresh Token

Get new access token using refresh token.

```http
POST /api/v1/auth/refresh
Content-Type: application/json
```

**Request Body:**

| Field        | Type   | Required | Description           |
| ------------ | ------ | -------- | --------------------- |
| refreshToken | string | Yes      | Current refresh token |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}
```

### Forgot Password

Request password reset email.

```http
POST /api/v1/auth/forgot-password
Content-Type: application/json
```

**Request Body:**

| Field | Type   | Required | Description   |
| ----- | ------ | -------- | ------------- |
| email | string | Yes      | Account email |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "If an account exists with this email, a reset link has been sent"
  }
}
```

### Reset Password

Reset password using token from email.

```http
POST /api/v1/auth/reset-password
Content-Type: application/json
```

**Request Body:**

| Field           | Type   | Required | Description            |
| --------------- | ------ | -------- | ---------------------- |
| token           | string | Yes      | Reset token from email |
| password        | string | Yes      | New password           |
| confirmPassword | string | Yes      | Password confirmation  |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "Password has been reset successfully"
  }
}
```

### Verify Email

Verify email address using token.

```http
POST /api/v1/auth/verify-email
Content-Type: application/json
```

**Request Body:**

| Field | Type   | Required | Description                   |
| ----- | ------ | -------- | ----------------------------- |
| token | string | Yes      | Verification token from email |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "Email verified successfully",
    "user": {
      "id": "usr_abc123def456",
      "emailVerified": true
    }
  }
}
```

---

## Users

### Get Current User

Get the authenticated user's profile.

```http
GET /api/v1/users/me
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123def456",
      "email": "user@example.com",
      "name": "John Doe",
      "avatarUrl": "https://cdn.tara.app/avatars/usr_abc123.jpg",
      "emailVerified": true,
      "timezone": "America/New_York",
      "locale": "en-US",
      "subscription": {
        "tier": "premium",
        "status": "active",
        "expiresAt": "2024-12-15T00:00:00.000Z"
      },
      "stats": {
        "totalSessions": 156,
        "totalMinutes": 1890,
        "currentStreak": 15,
        "longestStreak": 45
      },
      "createdAt": "2023-06-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}
```

### Update Current User

Update the authenticated user's profile.

```http
PATCH /api/v1/users/me
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request Body:**

| Field    | Type   | Required | Description         |
| -------- | ------ | -------- | ------------------- |
| name     | string | No       | Display name        |
| timezone | string | No       | User timezone       |
| locale   | string | No       | Preferred locale    |
| bio      | string | No       | Short bio (max 500) |

**Example Request:**

```json
{
  "name": "John D.",
  "timezone": "Europe/London",
  "bio": "Meditation enthusiast and mindfulness practitioner"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123def456",
      "name": "John D.",
      "timezone": "Europe/London",
      "bio": "Meditation enthusiast and mindfulness practitioner",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}
```

### Delete Account

Delete the authenticated user's account.

```http
DELETE /api/v1/users/me
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request Body:**

| Field    | Type   | Required | Description                       |
| -------- | ------ | -------- | --------------------------------- |
| password | string | Yes      | Current password for confirmation |
| reason   | string | No       | Deletion reason (for feedback)    |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "Account scheduled for deletion",
    "deletionDate": "2024-01-22T10:30:00.000Z"
  }
}
```

### Get User Settings

Get user preferences and settings.

```http
GET /api/v1/users/me/settings
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "settings": {
      "notifications": {
        "enabled": true,
        "dailyReminder": {
          "enabled": true,
          "time": "08:00",
          "timezone": "America/New_York"
        },
        "streakReminder": true,
        "newContent": true,
        "marketing": false
      },
      "meditation": {
        "preferredDuration": 10,
        "backgroundSounds": true,
        "defaultBackgroundSound": "rain",
        "autoPlay": false,
        "downloadOverWifiOnly": true
      },
      "appearance": {
        "theme": "system",
        "hapticFeedback": true
      },
      "privacy": {
        "shareProgress": false,
        "analytics": true
      }
    }
  }
}
```

### Update User Settings

Update user preferences and settings.

```http
PUT /api/v1/users/me/settings
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request Body:**

```json
{
  "notifications": {
    "enabled": true,
    "dailyReminder": {
      "enabled": true,
      "time": "07:30"
    }
  },
  "meditation": {
    "preferredDuration": 15,
    "backgroundSounds": true,
    "defaultBackgroundSound": "ocean"
  }
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "settings": {
      "notifications": {
        "enabled": true,
        "dailyReminder": {
          "enabled": true,
          "time": "07:30",
          "timezone": "America/New_York"
        }
      },
      "meditation": {
        "preferredDuration": 15,
        "backgroundSounds": true,
        "defaultBackgroundSound": "ocean"
      }
    }
  }
}
```

### List Devices

Get all registered devices for the user.

```http
GET /api/v1/users/me/devices
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "devices": [
      {
        "id": "dev_abc123",
        "deviceId": "550e8400-e29b-41d4-a716-446655440000",
        "deviceName": "iPhone 15 Pro",
        "platform": "ios",
        "osVersion": "17.2",
        "appVersion": "1.0.0",
        "lastUsed": "2024-01-15T10:30:00.000Z",
        "current": true,
        "pushEnabled": true
      },
      {
        "id": "dev_def456",
        "deviceId": "660e8400-e29b-41d4-a716-446655440000",
        "deviceName": "iPad Pro",
        "platform": "ios",
        "osVersion": "17.2",
        "appVersion": "1.0.0",
        "lastUsed": "2024-01-14T08:00:00.000Z",
        "current": false,
        "pushEnabled": true
      }
    ]
  }
}
```

### Remove Device

Remove a registered device.

```http
DELETE /api/v1/users/me/devices/:deviceId
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "Device removed successfully"
  }
}
```

---

## Meditations

### List Meditations

Get a paginated list of meditations.

```http
GET /api/v1/meditations
Authorization: Bearer <access_token>
```

**Query Parameters:**

| Parameter  | Type    | Default | Description                              |
| ---------- | ------- | ------- | ---------------------------------------- |
| page       | integer | 1       | Page number                              |
| limit      | integer | 20      | Items per page (max 100)                 |
| category   | string  | -       | Filter by category slug                  |
| duration   | string  | -       | Filter: short, medium, long              |
| instructor | string  | -       | Filter by instructor ID                  |
| level      | string  | -       | Filter: beginner, intermediate, advanced |
| search     | string  | -       | Search in title and description          |
| sort       | string  | popular | Sort: popular, newest, duration          |

**Example Request:**

```http
GET /api/v1/meditations?category=sleep&duration=medium&page=1&limit=10
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "med_abc123",
        "title": "Deep Sleep Journey",
        "description": "A calming meditation to guide you into restful sleep",
        "duration": 1200,
        "category": {
          "id": "cat_sleep",
          "name": "Sleep",
          "slug": "sleep",
          "icon": "moon"
        },
        "instructor": {
          "id": "inst_xyz789",
          "name": "Sarah Chen",
          "avatarUrl": "https://cdn.tara.app/instructors/sarah.jpg"
        },
        "thumbnailUrl": "https://cdn.tara.app/meditations/med_abc123/thumb.jpg",
        "isPremium": true,
        "level": "beginner",
        "tags": ["sleep", "relaxation", "nighttime"],
        "rating": 4.8,
        "totalPlays": 125000,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 45,
      "totalPages": 5,
      "hasNext": true,
      "hasPrev": false
    }
  }
}
```

### Get Meditation Details

Get detailed information about a specific meditation.

```http
GET /api/v1/meditations/:id
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "meditation": {
      "id": "med_abc123",
      "title": "Deep Sleep Journey",
      "description": "A calming meditation to guide you into restful sleep with gentle breathing exercises and body relaxation techniques.",
      "longDescription": "This guided meditation combines progressive muscle relaxation with visualization techniques to help you achieve deep, restorative sleep...",
      "duration": 1200,
      "category": {
        "id": "cat_sleep",
        "name": "Sleep",
        "slug": "sleep",
        "icon": "moon",
        "color": "#6366F1"
      },
      "instructor": {
        "id": "inst_xyz789",
        "name": "Sarah Chen",
        "bio": "Certified meditation teacher with 15 years of experience",
        "avatarUrl": "https://cdn.tara.app/instructors/sarah.jpg"
      },
      "thumbnailUrl": "https://cdn.tara.app/meditations/med_abc123/thumb.jpg",
      "coverUrl": "https://cdn.tara.app/meditations/med_abc123/cover.jpg",
      "isPremium": true,
      "level": "beginner",
      "tags": ["sleep", "relaxation", "nighttime", "breathing"],
      "chapters": [
        {
          "title": "Introduction",
          "startTime": 0,
          "duration": 60
        },
        {
          "title": "Breathing Exercise",
          "startTime": 60,
          "duration": 180
        },
        {
          "title": "Body Scan",
          "startTime": 240,
          "duration": 360
        },
        {
          "title": "Visualization",
          "startTime": 600,
          "duration": 480
        },
        {
          "title": "Drift to Sleep",
          "startTime": 1080,
          "duration": 120
        }
      ],
      "backgroundSounds": [
        {
          "id": "bg_rain",
          "name": "Gentle Rain",
          "previewUrl": "https://cdn.tara.app/sounds/rain_preview.mp3"
        },
        {
          "id": "bg_ocean",
          "name": "Ocean Waves",
          "previewUrl": "https://cdn.tara.app/sounds/ocean_preview.mp3"
        }
      ],
      "rating": 4.8,
      "ratingsCount": 12500,
      "totalPlays": 125000,
      "userProgress": {
        "completed": false,
        "lastPosition": 300,
        "playCount": 3,
        "isFavorite": true
      },
      "related": [
        {
          "id": "med_def456",
          "title": "Sleep Stories: The Forest",
          "duration": 1800,
          "thumbnailUrl": "https://cdn.tara.app/meditations/med_def456/thumb.jpg"
        }
      ],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-10T00:00:00.000Z"
    }
  }
}
```

### Get Audio Stream URL

Get a signed URL for streaming meditation audio.

```http
GET /api/v1/meditations/:id/audio
Authorization: Bearer <access_token>
```

**Query Parameters:**

| Parameter        | Type   | Description                      |
| ---------------- | ------ | -------------------------------- |
| quality          | string | Audio quality: low, medium, high |
| backgroundSound  | string | Background sound ID to mix       |
| backgroundVolume | number | Background volume (0.0-1.0)      |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "audioUrl": "https://cdn.tara.app/audio/med_abc123/high.m4a?token=...",
    "expiresAt": "2024-01-15T11:30:00.000Z",
    "duration": 1200,
    "format": "m4a",
    "quality": "high",
    "bitrate": 256,
    "backgroundSound": {
      "id": "bg_rain",
      "audioUrl": "https://cdn.tara.app/sounds/rain.m4a?token=...",
      "volume": 0.3
    }
  }
}
```

### Get Featured Meditations

Get curated featured meditations.

```http
GET /api/v1/meditations/featured
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "featured": {
      "hero": {
        "id": "med_hero123",
        "title": "New Year Intentions",
        "subtitle": "Set your intentions for the year ahead",
        "coverUrl": "https://cdn.tara.app/featured/hero.jpg",
        "meditation": { ... }
      },
      "dailyPick": {
        "id": "med_daily456",
        "title": "Morning Calm",
        "meditation": { ... }
      },
      "collections": [
        {
          "id": "col_stress",
          "title": "Stress Relief",
          "description": "Meditations for managing stress",
          "meditations": [ ... ]
        }
      ],
      "newReleases": [ ... ],
      "popular": [ ... ],
      "forYou": [ ... ]
    }
  }
}
```

### List Categories

Get all meditation categories.

```http
GET /api/v1/meditations/categories
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "categories": [
      {
        "id": "cat_sleep",
        "name": "Sleep",
        "slug": "sleep",
        "description": "Meditations for better sleep",
        "icon": "moon",
        "color": "#6366F1",
        "meditationCount": 45,
        "thumbnailUrl": "https://cdn.tara.app/categories/sleep.jpg"
      },
      {
        "id": "cat_stress",
        "name": "Stress & Anxiety",
        "slug": "stress",
        "description": "Find calm in stressful moments",
        "icon": "leaf",
        "color": "#10B981",
        "meditationCount": 62,
        "thumbnailUrl": "https://cdn.tara.app/categories/stress.jpg"
      },
      {
        "id": "cat_focus",
        "name": "Focus",
        "slug": "focus",
        "description": "Improve concentration and clarity",
        "icon": "target",
        "color": "#F59E0B",
        "meditationCount": 38,
        "thumbnailUrl": "https://cdn.tara.app/categories/focus.jpg"
      }
    ]
  }
}
```

### Search Meditations

Search meditations by keyword.

```http
GET /api/v1/meditations/search
Authorization: Bearer <access_token>
```

**Query Parameters:**

| Parameter | Type    | Required | Description        |
| --------- | ------- | -------- | ------------------ |
| q         | string  | Yes      | Search query       |
| page      | integer | No       | Page number        |
| limit     | integer | No       | Items per page     |
| filters   | object  | No       | Additional filters |

**Example Request:**

```http
GET /api/v1/meditations/search?q=sleep%20anxiety&limit=10
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "query": "sleep anxiety",
    "items": [
      {
        "id": "med_abc123",
        "title": "Calm Anxiety for Sleep",
        "matchedFields": ["title", "tags"],
        "relevanceScore": 0.95,
        ...
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 23
    },
    "suggestions": ["sleep meditation", "anxiety relief"]
  }
}
```

---

## Sessions

### Start Session

Start a new meditation session.

```http
POST /api/v1/sessions
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request Body:**

| Field           | Type    | Required | Description               |
| --------------- | ------- | -------- | ------------------------- |
| meditationId    | string  | Yes      | Meditation ID             |
| deviceId        | string  | No       | Device identifier         |
| backgroundSound | string  | No       | Background sound ID       |
| startPosition   | integer | No       | Start position in seconds |

**Example Request:**

```json
{
  "meditationId": "med_abc123",
  "deviceId": "550e8400-e29b-41d4-a716-446655440000",
  "backgroundSound": "bg_rain",
  "startPosition": 0
}
```

**Response (201 Created):**

```json
{
  "success": true,
  "data": {
    "session": {
      "id": "sess_xyz789",
      "meditationId": "med_abc123",
      "userId": "usr_abc123def456",
      "status": "active",
      "startedAt": "2024-01-15T10:30:00.000Z",
      "currentPosition": 0,
      "totalDuration": 1200,
      "backgroundSound": "bg_rain"
    }
  }
}
```

### List Sessions

Get user's meditation sessions.

```http
GET /api/v1/sessions
Authorization: Bearer <access_token>
```

**Query Parameters:**

| Parameter    | Type    | Description                       |
| ------------ | ------- | --------------------------------- |
| page         | integer | Page number                       |
| limit        | integer | Items per page                    |
| status       | string  | Filter: active, completed, paused |
| meditationId | string  | Filter by meditation              |
| from         | string  | Start date (ISO 8601)             |
| to           | string  | End date (ISO 8601)               |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "sess_xyz789",
        "meditation": {
          "id": "med_abc123",
          "title": "Deep Sleep Journey",
          "thumbnailUrl": "https://cdn.tara.app/meditations/med_abc123/thumb.jpg"
        },
        "status": "completed",
        "startedAt": "2024-01-15T10:30:00.000Z",
        "completedAt": "2024-01-15T10:50:00.000Z",
        "duration": 1200,
        "actualDuration": 1180
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156
    }
  }
}
```

### Get Session Details

Get details of a specific session.

```http
GET /api/v1/sessions/:id
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "session": {
      "id": "sess_xyz789",
      "meditation": {
        "id": "med_abc123",
        "title": "Deep Sleep Journey",
        "duration": 1200,
        "instructor": {
          "name": "Sarah Chen"
        }
      },
      "status": "completed",
      "startedAt": "2024-01-15T10:30:00.000Z",
      "completedAt": "2024-01-15T10:50:00.000Z",
      "pausedAt": null,
      "duration": 1200,
      "actualDuration": 1180,
      "currentPosition": 1200,
      "backgroundSound": "bg_rain",
      "backgroundVolume": 0.3,
      "deviceId": "550e8400-e29b-41d4-a716-446655440000",
      "deviceName": "iPhone 15 Pro"
    }
  }
}
```

### Update Session

Update session progress (e.g., pause, update position).

```http
PATCH /api/v1/sessions/:id
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request Body:**

| Field            | Type    | Description                    |
| ---------------- | ------- | ------------------------------ |
| status           | string  | Session status: paused, active |
| currentPosition  | integer | Current playback position      |
| backgroundSound  | string  | Background sound ID            |
| backgroundVolume | number  | Background volume (0.0-1.0)    |

**Example Request:**

```json
{
  "status": "paused",
  "currentPosition": 600
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "session": {
      "id": "sess_xyz789",
      "status": "paused",
      "currentPosition": 600,
      "pausedAt": "2024-01-15T10:40:00.000Z"
    }
  }
}
```

### Complete Session

Mark a session as completed.

```http
POST /api/v1/sessions/:id/complete
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request Body:**

| Field          | Type    | Description                 |
| -------------- | ------- | --------------------------- |
| actualDuration | integer | Actual time spent (seconds) |
| rating         | integer | Session rating (1-5)        |
| feedback       | string  | Optional feedback           |
| mood           | object  | Mood before/after           |

**Example Request:**

```json
{
  "actualDuration": 1180,
  "rating": 5,
  "mood": {
    "before": "anxious",
    "after": "calm"
  }
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "session": {
      "id": "sess_xyz789",
      "status": "completed",
      "completedAt": "2024-01-15T10:50:00.000Z",
      "actualDuration": 1180,
      "rating": 5
    },
    "progress": {
      "streakUpdated": true,
      "newStreak": 16,
      "minutesAdded": 20,
      "totalMinutes": 1910,
      "achievementsUnlocked": [
        {
          "id": "ach_streak15",
          "name": "Two Week Warrior",
          "description": "Maintain a 15-day meditation streak"
        }
      ]
    }
  }
}
```

---

## Favorites

### List Favorites

Get user's favorite meditations.

```http
GET /api/v1/favorites
Authorization: Bearer <access_token>
```

**Query Parameters:**

| Parameter | Type    | Description        |
| --------- | ------- | ------------------ |
| page      | integer | Page number        |
| limit     | integer | Items per page     |
| category  | string  | Filter by category |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "fav_abc123",
        "meditation": {
          "id": "med_abc123",
          "title": "Deep Sleep Journey",
          "duration": 1200,
          "thumbnailUrl": "https://cdn.tara.app/meditations/med_abc123/thumb.jpg",
          "category": {
            "name": "Sleep",
            "slug": "sleep"
          }
        },
        "addedAt": "2024-01-10T08:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 12
    }
  }
}
```

### Add to Favorites

Add a meditation to favorites.

```http
POST /api/v1/favorites
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request Body:**

| Field        | Type   | Required | Description   |
| ------------ | ------ | -------- | ------------- |
| meditationId | string | Yes      | Meditation ID |

**Response (201 Created):**

```json
{
  "success": true,
  "data": {
    "favorite": {
      "id": "fav_xyz789",
      "meditationId": "med_abc123",
      "addedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}
```

### Remove from Favorites

Remove a meditation from favorites.

```http
DELETE /api/v1/favorites/:meditationId
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "Removed from favorites"
  }
}
```

---

## History

### Get History

Get user's meditation history.

```http
GET /api/v1/history
Authorization: Bearer <access_token>
```

**Query Parameters:**

| Parameter | Type    | Description           |
| --------- | ------- | --------------------- |
| page      | integer | Page number           |
| limit     | integer | Items per page        |
| from      | string  | Start date (ISO 8601) |
| to        | string  | End date (ISO 8601)   |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "hist_abc123",
        "meditation": {
          "id": "med_abc123",
          "title": "Deep Sleep Journey",
          "duration": 1200,
          "thumbnailUrl": "https://cdn.tara.app/meditations/med_abc123/thumb.jpg"
        },
        "playedAt": "2024-01-15T10:30:00.000Z",
        "duration": 1180,
        "completed": true
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156
    }
  }
}
```

### Clear History

Clear all meditation history.

```http
DELETE /api/v1/history
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "History cleared",
    "itemsDeleted": 156
  }
}
```

### Remove History Entry

Remove a specific history entry.

```http
DELETE /api/v1/history/:id
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "message": "History entry removed"
  }
}
```

---

## Progress

### Get Streak

Get user's current meditation streak.

```http
GET /api/v1/progress/streak
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "streak": {
      "current": 15,
      "longest": 45,
      "lastActivityDate": "2024-01-15",
      "startDate": "2024-01-01",
      "isActiveToday": true,
      "freezesAvailable": 2,
      "freezesUsed": 1
    }
  }
}
```

### Get Statistics

Get user's meditation statistics.

```http
GET /api/v1/progress/stats
Authorization: Bearer <access_token>
```

**Query Parameters:**

| Parameter | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| period    | string | Time period: week, month, year, all |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "stats": {
      "period": "month",
      "totalSessions": 28,
      "totalMinutes": 420,
      "averageSessionLength": 15,
      "longestSession": 30,
      "uniqueMeditations": 15,
      "favoriteCategory": {
        "name": "Sleep",
        "sessions": 12
      },
      "favoriteInstructor": {
        "name": "Sarah Chen",
        "sessions": 18
      },
      "byDay": [
        { "date": "2024-01-01", "minutes": 15, "sessions": 1 },
        { "date": "2024-01-02", "minutes": 20, "sessions": 2 }
      ],
      "byCategory": [
        { "category": "Sleep", "minutes": 180, "sessions": 12 },
        { "category": "Stress", "minutes": 120, "sessions": 8 }
      ],
      "moodImprovement": {
        "averageBefore": 3.2,
        "averageAfter": 4.5,
        "improvement": 40.6
      }
    }
  }
}
```

### Get Progress History

Get detailed progress history.

```http
GET /api/v1/progress/history
Authorization: Bearer <access_token>
```

**Query Parameters:**

| Parameter | Type   | Description                    |
| --------- | ------ | ------------------------------ |
| period    | string | Time period: week, month, year |
| groupBy   | string | Grouping: day, week, month     |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "history": [
      {
        "date": "2024-01-15",
        "sessions": 2,
        "minutes": 30,
        "completed": 2,
        "streak": 15
      },
      {
        "date": "2024-01-14",
        "sessions": 1,
        "minutes": 20,
        "completed": 1,
        "streak": 14
      }
    ],
    "summary": {
      "totalDays": 15,
      "activeDays": 15,
      "totalSessions": 28,
      "totalMinutes": 420
    }
  }
}
```

### Get Achievements

Get user's achievements and badges.

```http
GET /api/v1/progress/achievements
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "achievements": {
      "unlocked": [
        {
          "id": "ach_first_session",
          "name": "First Steps",
          "description": "Complete your first meditation",
          "icon": "🧘",
          "unlockedAt": "2023-06-15T10:30:00.000Z",
          "category": "milestones"
        },
        {
          "id": "ach_streak7",
          "name": "Week Warrior",
          "description": "Maintain a 7-day streak",
          "icon": "🔥",
          "unlockedAt": "2023-06-22T10:30:00.000Z",
          "category": "streaks"
        },
        {
          "id": "ach_streak15",
          "name": "Two Week Warrior",
          "description": "Maintain a 15-day streak",
          "icon": "🔥🔥",
          "unlockedAt": "2024-01-15T10:30:00.000Z",
          "category": "streaks"
        }
      ],
      "locked": [
        {
          "id": "ach_streak30",
          "name": "Monthly Master",
          "description": "Maintain a 30-day streak",
          "icon": "🔥🔥🔥",
          "category": "streaks",
          "progress": {
            "current": 15,
            "target": 30,
            "percentage": 50
          }
        }
      ],
      "categories": [
        {
          "id": "milestones",
          "name": "Milestones",
          "unlocked": 5,
          "total": 10
        },
        { "id": "streaks", "name": "Streaks", "unlocked": 3, "total": 8 },
        { "id": "explorer", "name": "Explorer", "unlocked": 2, "total": 6 }
      ]
    }
  }
}
```

---

## Subscriptions

### Get Subscription Status

Get current subscription status.

```http
GET /api/v1/subscriptions/status
Authorization: Bearer <access_token>
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "subscription": {
      "tier": "premium",
      "status": "active",
      "platform": "ios",
      "productId": "tara_premium_annual",
      "startDate": "2024-01-01T00:00:00.000Z",
      "expiresAt": "2024-12-31T23:59:59.000Z",
      "autoRenew": true,
      "trialEnd": null,
      "canceledAt": null,
      "features": [
        "unlimited_meditations",
        "offline_downloads",
        "background_sounds",
        "no_ads"
      ]
    },
    "entitlements": {
      "premium_content": true,
      "offline_downloads": true,
      "background_sounds": true,
      "download_limit": null
    }
  }
}
```

### Verify Receipt

Verify an in-app purchase receipt.

```http
POST /api/v1/subscriptions/verify
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request Body:**

| Field     | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| receipt   | string | Yes      | Receipt data (base64)  |
| platform  | string | Yes      | Platform: ios, android |
| productId | string | No       | Expected product ID    |

**Example Request (iOS):**

```json
{
  "receipt": "MIITtgYJKoZIhvc...",
  "platform": "ios",
  "productId": "tara_premium_annual"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "valid": true,
    "subscription": {
      "tier": "premium",
      "status": "active",
      "productId": "tara_premium_annual",
      "expiresAt": "2024-12-31T23:59:59.000Z",
      "isTrialPeriod": false,
      "autoRenew": true
    },
    "entitlements": {
      "premium_content": true,
      "offline_downloads": true
    }
  }
}
```

### Restore Purchases

Restore previous purchases.

```http
POST /api/v1/subscriptions/restore
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request Body:**

| Field    | Type   | Required | Description            |
| -------- | ------ | -------- | ---------------------- |
| receipts | array  | Yes      | Array of receipt data  |
| platform | string | Yes      | Platform: ios, android |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "restored": true,
    "subscription": {
      "tier": "premium",
      "status": "active",
      "expiresAt": "2024-12-31T23:59:59.000Z"
    },
    "restoredProducts": [
      {
        "productId": "tara_premium_annual",
        "purchaseDate": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}
```
