Complete reference for all Tara API endpoints with request/response examples.
Table of Contents#
Health & Status#
Health Check#
Check if the API is running.
GET /health
Response (200 OK):
{
"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.).
GET /ready
Response (200 OK):
{
"status": "ready",
"checks": {
"database": "ok",
"redis": "ok",
"storage": "ok"
}
}
Response (503 Service Unavailable):
{
"status": "not_ready",
"checks": {
"database": "ok",
"redis": "failed",
"storage": "ok"
}
}
Version Information#
Get API version and build information.
GET /version
Response (200 OK):
{
"version": "1.0.0",
"build": "sha-abc1234",
"environment": "production",
"node": "22.0.0"
}
Authentication#
Register#
Create a new user account.
POST /api/v1/auth/register
Content-Type: application/json
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
| 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:
{
"email": "user@example.com",
"password": "SecurePassword123!",
"name": "John Doe",
"acceptedTerms": true,
"marketingConsent": false,
"timezone": "America/New_York"
}
Response (201 Created):
{
"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.
POST /api/v1/auth/login
Content-Type: application/json
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
| 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:
{
"email": "user@example.com",
"password": "SecurePassword123!",
"deviceId": "550e8400-e29b-41d4-a716-446655440000",
"deviceName": "iPhone 15 Pro",
"platform": "ios"
}
Response (200 OK):
{
"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.
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):
{
"success": true,
"data": {
"message": "Successfully logged out",
"devicesLoggedOut": 1
}
}
Refresh Token#
Get new access token using refresh token.
POST /api/v1/auth/refresh
Content-Type: application/json
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
| refreshToken | string | Yes | Current refresh token |
Response (200 OK):
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"expiresIn": 900,
"tokenType": "Bearer"
}
}
Forgot Password#
Request password reset email.
POST /api/v1/auth/forgot-password
Content-Type: application/json
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Account email |
Response (200 OK):
{
"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.
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):
{
"success": true,
"data": {
"message": "Password has been reset successfully"
}
}
Verify Email#
Verify email address using token.
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):
{
"success": true,
"data": {
"message": "Email verified successfully",
"user": {
"id": "usr_abc123def456",
"emailVerified": true
}
}
}
Users#
Get Current User#
Get the authenticated user's profile.
GET /api/v1/users/me
Authorization: Bearer <access_token>
Response (200 OK):
{
"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.
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:
{
"name": "John D.",
"timezone": "Europe/London",
"bio": "Meditation enthusiast and mindfulness practitioner"
}
Response (200 OK):
{
"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.
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):
{
"success": true,
"data": {
"message": "Account scheduled for deletion",
"deletionDate": "2024-01-22T10:30:00.000Z"
}
}
Get User Settings#
Get user preferences and settings.
GET /api/v1/users/me/settings
Authorization: Bearer <access_token>
Response (200 OK):
{
"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.
PUT /api/v1/users/me/settings
Authorization: Bearer <access_token>
Content-Type: application/json
Request Body:
{
"notifications": {
"enabled": true,
"dailyReminder": {
"enabled": true,
"time": "07:30"
}
},
"meditation": {
"preferredDuration": 15,
"backgroundSounds": true,
"defaultBackgroundSound": "ocean"
}
}
Response (200 OK):
{
"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.
GET /api/v1/users/me/devices
Authorization: Bearer <access_token>
Response (200 OK):
{
"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.
DELETE /api/v1/users/me/devices/:deviceId
Authorization: Bearer <access_token>
Response (200 OK):
{
"success": true,
"data": {
"message": "Device removed successfully"
}
}
Meditations#
List Meditations#
Get a paginated list of meditations.
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:
GET /api/v1/meditations?category=sleep&duration=medium&page=1&limit=10
Response (200 OK):
{
"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.
GET /api/v1/meditations/:id
Authorization: Bearer <access_token>
Response (200 OK):
{
"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.
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):
{
"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.
GET /api/v1/meditations/featured
Authorization: Bearer <access_token>
Response (200 OK):
{
"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.
GET /api/v1/meditations/categories
Authorization: Bearer <access_token>
Response (200 OK):
{
"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.
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:
GET /api/v1/meditations/search?q=sleep%20anxiety&limit=10
Response (200 OK):
{
"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.
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:
{
"meditationId": "med_abc123",
"deviceId": "550e8400-e29b-41d4-a716-446655440000",
"backgroundSound": "bg_rain",
"startPosition": 0
}
Response (201 Created):
{
"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.
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):
{
"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.
GET /api/v1/sessions/:id
Authorization: Bearer <access_token>
Response (200 OK):
{
"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).
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:
{
"status": "paused",
"currentPosition": 600
}
Response (200 OK):
{
"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.
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:
{
"actualDuration": 1180,
"rating": 5,
"mood": {
"before": "anxious",
"after": "calm"
}
}
Response (200 OK):
{
"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.
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):
{
"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.
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):
{
"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.
DELETE /api/v1/favorites/:meditationId
Authorization: Bearer <access_token>
Response (200 OK):
{
"success": true,
"data": {
"message": "Removed from favorites"
}
}
History#
Get History#
Get user's meditation history.
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):
{
"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.
DELETE /api/v1/history
Authorization: Bearer <access_token>
Response (200 OK):
{
"success": true,
"data": {
"message": "History cleared",
"itemsDeleted": 156
}
}
Remove History Entry#
Remove a specific history entry.
DELETE /api/v1/history/:id
Authorization: Bearer <access_token>
Response (200 OK):
{
"success": true,
"data": {
"message": "History entry removed"
}
}
Progress#
Get Streak#
Get user's current meditation streak.
GET /api/v1/progress/streak
Authorization: Bearer <access_token>
Response (200 OK):
{
"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.
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):
{
"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.
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):
{
"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.
GET /api/v1/progress/achievements
Authorization: Bearer <access_token>
Response (200 OK):
{
"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.
GET /api/v1/subscriptions/status
Authorization: Bearer <access_token>
Response (200 OK):
{
"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.
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):
{
"receipt": "MIITtgYJKoZIhvc...",
"platform": "ios",
"productId": "tara_premium_annual"
}
Response (200 OK):
{
"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.
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):
{
"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"
}
]
}
}