Myndy API Documentation

Overview

Myndy API is a comprehensive health and productivity data platform with over 100 endpoints across multiple functional categories. The system features optimized batch processing, comprehensive authentication, and seamless mobile integration.

Base URL

All API endpoints are relative to:

https://www.myndyai.com

Core Features

• Health Data Processing: Optimized batch uploads with comprehensive deduplication
• Location Tracking: iOS-compatible GPS data with consolidated storage (11,932+ records migrated)
• Authentication: JWT tokens with 90-day mobile support, API keys, and OAuth integration
• Task Management: Todoist integration with real-time sync
• Scanning: Barcode/QR code scanning with product lookup
• SMS Integration: TextBee webhook processing and messaging
• Status API: Real-time user context for AI integration
• Device Management: Multi-device registration and sync

Performance Optimizations

• Batch Processing: Health data uploads reduced from 7,500+ queries to single bulk operations
• Deduplication: 4-level deduplication (ID-based, semantic, cross-source, value-based)
• Database Optimization: JSONB indexing and constraint handling
• Mobile Integration: Optimized for iOS HealthKit and location services

Authentication

The API supports multiple authentication methods including JWT tokens, API keys, and OAuth integration with external services like Todoist.

Authentication Methods

• OAuth 2.0 Authentication: Standard OAuth flow for all API access
• OAuth External Integrations: Connect external services like Todoist

Security & Data Isolation: All API endpoints require proper OAuth 2.0 authentication. Every database operation is automatically scoped to the authenticated user's ID extracted from the OAuth token, ensuring complete data isolation between users. Only OAuth authentication is supported - no backdoor API keys or alternative access methods.

🔒 Automatic User Data Scoping

• OAuth Token Extraction: All endpoints extract user_id from OAuth token context
• Database Query Scoping: Every query includes WHERE user_id = %s automatically
• Data Isolation: Users can only access their own data - no cross-user data leakage
• Table Security: All tables include user_id column with proper indexing
• No Manual User ID: User ID is never accepted from request parameters - only from OAuth token

response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_CALLBACK_URL
&scope=user_data+health_data
&state=RANDOM_STATE_VALUE

YOUR_CALLBACK_URL?code=AUTHORIZATION_CODE&state=RANDOM_STATE_VALUE

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=YOUR_CALLBACK_URL

{
  "access_token": "oauth2_access_token_here",
  "token_type": "Bearer",
  "expires_in": 7776000,
  "refresh_token": "oauth2_refresh_token_here",
  "scope": "user_data health_data"
}

{
  "sub": "user-id",
  "email": "user@example.com",
  "name": "User Name",
  "preferred_username": "username"
}

Using OAuth Authentication

OAuth Token: Include in Authorization header: Authorization: Bearer <oauth_access_token>

Additional OAuth Endpoints

• POST /oauth/token - Refresh OAuth token (with refresh_token grant)
• POST /oauth/revoke - Revoke OAuth access token
• GET /api/v1/auth/oauth/connect/todoist - Connect Todoist (OAuth required)
• POST /api/v1/auth/oauth/disconnect/todoist - Disconnect Todoist
• GET /api/v1/auth/oauth/status/todoist - Check Todoist connection status

Location Data

iOS-compatible location tracking with consolidated database storage. All location data has been migrated to the dedicated location_data table with 11,932 total records.

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "altitude": 50.0,
  "horizontalAccuracy": 10.0,
  "verticalAccuracy": 5.0,
  "timestamp": "2025-09-28T03:45:00Z",
  "speed": 5.2,
  "course": 180.0
}

{
  "locations": [
    {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "horizontalAccuracy": 10.0,
      "timestamp": "2025-09-28T03:45:00Z"
    }
  ]
}

{
  "success": true,
  "inserted": 1,
  "total": 1,
  "message": "Successfully saved 1 location points",
  "errors": []
}

{
  "success": true,
  "locations": [
    {
      "id": "location-uuid",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "altitude": 50.0,
      "horizontalAccuracy": 10.0,
      "timestamp": "2025-09-28T03:45:00Z",
      "speed": 5.2,
      "course": 180.0
    }
  ],
  "count": 1
}

Database Architecture

• Consolidated Storage: All location data in dedicated location_data table
• Migration Complete: 11,930 records migrated from health_data, 2 new iOS uploads
• GPS Precision: 6-decimal places (~1 meter accuracy)
• Field Mapping: horizontalAccuracy → accuracy (optional, defaults to 10.0), course → heading

User Management

User profile management, device registration, and account operations.

{
  "id": "user-id",
  "email": "user@example.com",
  "name": "User Name",
  "role": "user",
  "created_at": "2025-09-28T14:30:00Z"
}

{
  "name": "iPhone 15 Pro"
}

{
  "id": "device-id",
  "name": "iPhone 15 Pro",
  "lastSync": "2025-09-28T14:30:00Z"
}

Additional Endpoints

• GET /api/v1/user/profile - Get user profile
• PUT /api/v1/user/profile - Update user profile
• GET /api/v1/device/list - List user's devices

SMS & Messaging

SMS webhook processing, TextBee integration, and message management.

{
  "from": "+1234567890",
  "to": "+0987654321",
  "message": "Hello from SMS",
  "timestamp": "2025-09-28T14:30:00Z"
}

{
  "status": "received",
  "message_id": "sms-uuid",
  "processed": true
}

{
  "messages": [
    {
      "id": "sms-uuid",
      "from": "+1234567890",
      "to": "+0987654321",
      "message": "Hello from SMS",
      "timestamp": "2025-09-28T14:30:00Z",
      "processed": true
    }
  ],
  "count": 1
}

Additional Endpoints

• POST /api/v1/sms/send - Send SMS message
• GET /api/v1/sms/stats - Get SMS statistics
• POST /api/v1/sms/process/{message_id} - Process specific message
• GET /api/v1/sms/unprocessed - Get unprocessed messages
• POST /api/v1/sms/archive/{message_id} - Archive message
• POST /api/v1/sms/bulk-archive - Bulk archive messages

Health Data

Comprehensive health metrics management with optimized batch processing and comprehensive deduplication. All endpoints require OAuth JWT authentication.

{
  "id": "uuid-v4",
  "type": "heart_rate",
  "timestamp": "2025-09-28T14:30:00Z",
  "source": "healthkit",
  "value": 72.0,
  "data": {
    "unit": "bpm",
    "confidence": 0.98
  }
}

{
  "id": "uuid-v4",
  "message": "Health data point created"
}

[
  {
    "id": "uuid-v4-1",
    "type": "heart_rate",
    "timestamp": "2025-09-28T14:30:00Z",
    "source": "healthkit",
    "value": 72.0
  },
  {
    "id": "uuid-v4-2",
    "type": "steps",
    "timestamp": "2025-09-28T14:30:00Z",
    "source": "healthkit",
    "value": 10000
  }
]

{
  "inserted": 1850,
  "updated": 150,
  "total": 2000,
  "success_rate": "100.0%",
  "errors": []
}

{
  "data": [
    {
      "id": "uuid-v4",
      "type": "heart_rate",
      "timestamp": "2025-09-28T14:30:00Z",
      "source": "healthkit",
      "value": 72.0,
      "user_id": "user-id"
    }
  ],
  "nextPageToken": "pagination-token"
}

Additional Endpoints

• POST /api/v1/healthdata/bulk - Bulk upload in grouped format (50%+ smaller payloads)
• GET /api/v1/healthdata/aggregate - Aggregated metrics and summaries
• GET /api/v1/health - Alias endpoint for health data retrieval

Status & Context API

Real-time user context with intelligent data aggregation from existing health and location data. All endpoints require OAuth JWT authentication.

{
  "user_id": "user-id",
  "timestamp": "2025-09-28T14:30:00Z",
  "mood": "focused",
  "stress_level": 3,
  "activity": "working",
  "health": {
    "heart_rate": 72,
    "steps": 8500,
    "sleep_quality": "good"
  },
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "accuracy": 10.5
  },
  "context_tags": ["meeting", "focused"],
  "source": "aggregated"
}

{
  "mood": "excited",
  "health": {
    "heart_rate": 78
  },
  "context_tags": ["presentation"],
  "change_type": "partial"
}

{
  "success": true,
  "status_id": "uuid-v4",
  "timestamp": "2025-09-28T14:30:00Z",
  "change_type": "partial"
}

Additional Endpoints

• GET /api/v1/status/history - Historical status records with time filtering
• POST /api/v1/status/mood - Record mood entry
• GET /api/v1/status/mood - Get mood history

Todolist API Endpoints

Manage tasks and projects with seamless integration to connected productivity services like Todoist. Requires authentication and automatically uses your connected Todoist account if available.

{
  "status": "success",
  "tasks": [
    {
      "id": "123456789",
      "content": "Buy groceries",
      "description": "Milk, bread, eggs",
      "completed": false,
      "priority": 2,
      "due_date": "2025-05-31T10:00:00Z",
      "project_id": "987654321",
      "labels": ["shopping", "urgent"],
      "url": "https://todoist.com/showTask?id=123456789",
      "created_at": "2025-05-30T09:00:00Z",
      "updated_at": "2025-05-30T09:00:00Z"
    }
  ]
}

{
  "content": "Buy groceries",
  "description": "Milk, bread, eggs",
  "due_date": "2025-05-31T10:00:00Z",
  "priority": 2,
  "labels": ["shopping", "urgent"]
}

{
  "content": "Updated task title",
  "completed": true
}

{
  "status": "success",
  "projects": [
    {
      "id": "987654321",
      "name": "Work",
      "color": "blue",
      "is_favorite": false,
      "url": "https://todoist.com/app/project/987654321"
    }
  ]
}

{
  "status": "success",
  "service": "todoist",
  "connected": true,
  "message": "Service is operational"
}

Scan API

Barcode, QR code, and NFC tag scanning with product lookup and data management.

{
  "code": "123456789012",
  "type": "barcode",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

{
  "code": "123456789012",
  "type": "UPC",
  "product": {
    "name": "Example Product",
    "brand": "Example Brand",
    "category": "Food",
    "image_url": "https://example.com/image.jpg"
  },
  "scan_count": 5,
  "last_scanned": "2025-05-30T10:00:00Z"
}

{
  "total_scans": 150,
  "unique_codes": 75,
  "most_scanned": {
    "code": "123456789012",
    "count": 8,
    "product_name": "Example Product"
  },
  "scan_types": {
    "barcode": 120,
    "qr_code": 25,
    "nfc": 5
  },
  "recent_activity": {
    "last_7_days": 12,
    "last_30_days": 45
  }
}

{
  "name": "S-Balance",
  "brand": "Vital Health",
  "category": "Supplements",
  "description": "Natural balance supplement",
  "nutrition": {
    "serving_size": "2 tablets",
    "calories": 5
  },
  "ingredients": ["Magnesium", "Calcium", "Vitamin D3"]
}

{
  "name": "S-Balance",
  "brand": "Vital Health",
  "barcode": ""
}

Utility Endpoints

{
  "status": "healthy",
  "timestamp": "2023-05-01T12:00:00Z"
}

Error Responses

All API errors follow a consistent format:

{
  "error": "Error message"
}

Common Error Codes

Rate Limiting & Performance

The API implements comprehensive rate limiting and performance optimizations:

Rate Limits

• Authentication endpoints: 10 requests per minute
• Registration: 3 requests per hour
• General API endpoints: 200 requests per day, 50 per hour (with JWT)
• Health data batch: 20 requests per hour
• SMS endpoints: 100 requests per hour

Performance Features

• Health Data Optimization: 99.99% reduction in database queries through batch processing
• 4-Level Deduplication: ID-based, semantic, cross-source, value-based
• Bulk Processing: Up to 5,000 health records per batch
• Location Consolidation: 11,932+ records in optimized storage
• JSONB Indexing: Fast status and health data queries

Security: All endpoints require OAuth JWT authentication. Rate limit exceeded returns 429 Too Many Requests.

Client Libraries

We provide client libraries for easy integration with the Myndy API:

Mobile Integration

For React Native mobile applications:

// Path: clients/mobile/myndyApi.js
// Include in your React Native project

Usage example:

import { MyndyApiClient } from './myndyApi';

const apiClient = new MyndyApiClient({
  apiUrl: 'https://www.myndyai.com',
  credentials: {
    email: 'user@example.com',
    password: 'secure-password'
  }
});

// Upload health data
const result = await apiClient.uploadData({
  type: 'health',
  data: {
    heartRate: 72,
    steps: 10000,
    sleepHours: 7.5
  }
});

AI Integration

For AI assistants:

# Path: clients/ai/myndy_client.py
# Include in your Python project

Usage example:

from myndy_client import MyndyAiClient

client = MyndyAiClient(
    api_url='https://www.myndyai.com',
    credentials={
        'email': 'ai@example.com',
        'password': 'secure-password'
    }
)

# Get latest user data
user_data = client.get_latest_data(user_id='user-id')

# Process with AI model
result = client.process_data(user_data)