Eve library

Tara API Endpoint Reference

Guide

Revision 1

On this page

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

Table of Contents#


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 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"
      }
    ]
  }
}