MindPeeker Logo
Specifications

API Endpoints Reference

Complete reference documentation for all MindPeeker API endpoints

Base Configuration

Base URLs

Production: https://api.mindpeeker.com/v1
Staging: https://staging-api.mindpeeker.com/v1
Development: https://dev-api.mindpeeker.com/v1

Authentication Headers

Authorization: Bearer <jwt_token>
X-API-Key: <api_key>
X-Client-Version: 2024-01-01
Content-Type: application/json

Rate Limits

  • Basic Tier: 100 requests/minute, 1,000 requests/day
  • Professional Tier: 1,000 requests/minute, 10,000 requests/day
  • Enterprise Tier: 10,000 requests/minute, 100,000 requests/day

Authentication Endpoints

Register User

POST /auth/register

Request Body:

{
  "email": "user@example.com",
  "username": "johndoe",
  "password": "securePassword123",
  "tier": "basic",
  "marketing_consent": true
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user_123456789",
      "email": "user@example.com",
      "username": "johndoe",
      "tier": "basic",
      "created_at": "2024-01-01T00:00:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": "User registered successfully"
}

Login

POST /auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user_123456789",
      "email": "user@example.com",
      "username": "johndoe",
      "tier": "professional"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 86400
  },
  "message": "Login successful"
}

Refresh Token

POST /auth/refresh

Request Body:

{
  "refresh_token": "refresh_token_here"
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 86400
  },
  "message": "Token refreshed successfully"
}

Logout

POST /auth/logout

Headers:

Authorization: Bearer <jwt_token>

Response:

{
  "success": true,
  "message": "Logout successful"
}

User Management Endpoints

Get User Profile

GET /users/me

Response:

{
  "success": true,
  "data": {
    "id": "user_123456789",
    "email": "user@example.com",
    "username": "johndoe",
    "tier": "professional",
    "credits": 850,
    "created_at": "2024-01-01T00:00:00Z",
    "last_login": "2024-01-15T10:30:00Z",
    "preferences": {
      "notifications": true,
      "theme": "dark",
      "language": "en"
    },
    "usage_stats": {
      "sessions_this_month": 45,
      "total_sessions": 234,
      "success_rate": 0.87
    }
  }
}

Update User Profile

PUT /users/me

Request Body:

{
  "username": "newusername",
  "preferences": {
    "notifications": false,
    "theme": "light",
    "language": "es"
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "user_123456789",
    "username": "newusername",
    "preferences": {
      "notifications": false,
      "theme": "light",
      "language": "es"
    }
  },
  "message": "Profile updated successfully"
}

Get Usage Statistics

GET /users/me/stats

Query Parameters:

  • period: day, week, month, year (default: month)
  • start_date: ISO 8601 date string
  • end_date: ISO 8601 date string

Response:

{
  "success": true,
  "data": {
    "period": "month",
    "sessions": {
      "total": 45,
      "completed": 42,
      "pending": 3,
      "failed": 0
    },
    "credits_used": 180,
    "credits_remaining": 820,
    "success_rate": 0.933,
    "average_confidence": 0.78,
    "session_types": {
      "remote_viewing": 20,
      "dowsing": 15,
      "precognition": 10
    },
    "daily_breakdown": [
      {
        "date": "2024-01-01",
        "sessions": 2,
        "credits_used": 8
      }
    ]
  }
}

Session Management Endpoints

Create Session

POST /sessions

Request Body:

{
  "cue": "Describe the location of the missing aircraft in the Pacific Ocean",
  "session_type": "remote_viewing",
  "parameters": {
    "duration": 1800,
    "confidence_threshold": 0.7,
    "analysis_types": ["visual", "spatial", "temporal"],
    "priority": "normal"
  },
  "metadata": {
    "case_id": "CASE_12345",
    "client_reference": "REF_67890",
    "tags": ["aviation", "search", "pacific"]
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "session_123456789",
    "cue": "Describe the location of the missing aircraft in the Pacific Ocean",
    "session_type": "remote_viewing",
    "status": "pending",
    "created_at": "2024-01-01T10:00:00Z",
    "estimated_completion": "2024-01-01T10:30:00Z",
    "credits_required": 10,
    "parameters": {
      "duration": 1800,
      "confidence_threshold": 0.7
    },
    "websocket_url": "wss://api.mindpeeker.com/v1/ws/session_123456789"
  },
  "message": "Session created successfully"
}

Get Session Details

GET /sessions/{session_id}

Response:

{
  "success": true,
  "data": {
    "id": "session_123456789",
    "cue": "Describe the location of the missing aircraft in the Pacific Ocean",
    "session_type": "remote_viewing",
    "status": "completed",
    "created_at": "2024-01-01T10:00:00Z",
    "started_at": "2024-01-01T10:01:00Z",
    "completed_at": "2024-01-01T10:28:00Z",
    "duration": 1620,
    "credits_used": 8,
    "confidence_score": 0.82,
    "results": {
      "summary": "The aircraft is located approximately 200 miles northeast of Hawaii...",
      "coordinates": {
        "latitude": 22.5,
        "longitude": -152.3,
        "accuracy_radius": 15
      },
      "visual_data": [
        {
          "type": "landscape",
          "description": "Mountainous terrain with dense vegetation",
          "confidence": 0.89
        }
      ],
      "analysis_types": ["visual", "spatial", "temporal"]
    },
    "metadata": {
      "case_id": "CASE_12345",
      "client_reference": "REF_67890",
      "tags": ["aviation", "search", "pacific"]
    }
  }
}

List User Sessions

GET /sessions

Query Parameters:

  • status: pending, processing, completed, failed
  • session_type: remote_viewing, dowsing, precognition, intuitive_analysis
  • limit: Number of results (default: 20, max: 100)
  • offset: Pagination offset (default: 0)
  • sort_by: created_at, completed_at, confidence_score
  • order: asc, desc (default: desc)

Response:

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "session_123456789",
        "cue": "Describe the location of the missing aircraft",
        "session_type": "remote_viewing",
        "status": "completed",
        "created_at": "2024-01-01T10:00:00Z",
        "completed_at": "2024-01-01T10:28:00Z",
        "confidence_score": 0.82,
        "credits_used": 8
      }
    ],
    "pagination": {
      "total": 45,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  }
}

Update Session

PUT /sessions/{session_id}

Request Body:

{
  "parameters": {
    "confidence_threshold": 0.8,
    "priority": "high"
  },
  "metadata": {
    "tags": ["aviation", "search", "pacific", "urgent"]
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "session_123456789",
    "parameters": {
      "confidence_threshold": 0.8,
      "priority": "high"
    },
    "metadata": {
      "tags": ["aviation", "search", "pacific", "urgent"]
    }
  },
  "message": "Session updated successfully"
}

Cancel Session

DELETE /sessions/{session_id}

Response:

{
  "success": true,
  "message": "Session cancelled successfully",
  "refund": {
    "credits_refunded": 5,
    "refund_reason": "User cancellation"
  }
}

Analysis Endpoints

Get Analysis Results

GET /sessions/{session_id}/analysis

Response:

{
  "success": true,
  "data": {
    "session_id": "session_123456789",
    "analysis_id": "analysis_987654321",
    "status": "completed",
    "completed_at": "2024-01-01T10:28:00Z",
    "confidence_score": 0.82,
    "results": {
      "summary": "Based on the psychic analysis, the aircraft is located...",
      "key_findings": [
        {
          "type": "location",
          "description": "Approximately 200 miles northeast of Hawaii",
          "confidence": 0.89
        },
        {
          "type": "condition",
          "description": "Aircraft is largely intact but submerged",
          "confidence": 0.76
        }
      ],
      "detailed_analysis": {
        "spatial_data": {
          "coordinates": {
            "latitude": 22.5,
            "longitude": -152.3,
            "accuracy_radius": 15
          },
          "terrain": "Mountainous underwater terrain",
          "depth": "Approximately 2,000 meters"
        },
        "temporal_data": {
          "time_of_event": "2023-12-15T14:30:00Z",
          "current_status": "Static, no recent movement"
        },
        "visual_data": [
          {
            "type": "aerial_view",
            "description": "Metallic debris field visible on ocean floor",
            "confidence": 0.84
          }
        ]
      },
      "recommendations": [
        "Focus search efforts in the specified coordinates",
        "Use deep-sea sonar equipment for verification",
        "Consider ocean current patterns in search planning"
      ]
    },
    "metadata": {
      "analysis_duration": 1620,
      "model_version": "rv-v2.1.0",
      "processing_nodes": 8,
      "data_points_analyzed": 15420
    }
  }
}

Get Analysis History

GET /sessions/{session_id}/analysis/history

Response:

{
  "success": true,
  "data": {
    "analysis_history": [
      {
        "timestamp": "2024-01-01T10:05:00Z",
        "stage": "initial_processing",
        "confidence": 0.45,
        "notes": "Initial cue analysis and pattern recognition"
      },
      {
        "timestamp": "2024-01-01T10:15:00Z",
        "stage": "deep_analysis",
        "confidence": 0.67,
        "notes": "Neural network processing and cross-validation"
      },
      {
        "timestamp": "2024-01-01T10:28:00Z",
        "stage": "final_validation",
        "confidence": 0.82,
        "notes": "Final confidence scoring and result compilation"
      }
    ]
  }
}

Billing Endpoints

Get Billing Information

GET /billing

Response:

{
  "success": true,
  "data": {
    "tier": "professional",
    "monthly_fee": 299,
    "credits": {
      "included": 1000,
      "used": 180,
      "remaining": 820,
      "reset_date": "2024-02-01T00:00:00Z"
    },
    "usage": {
      "current_month": {
        "sessions": 45,
        "api_calls": 1250,
        "storage_gb": 2.3
      },
      "last_month": {
        "sessions": 38,
        "api_calls": 980,
        "storage_gb": 1.8
      }
    },
    "payment_method": {
      "type": "card",
      "last_four": "4242",
      "expiry": "12/25"
    },
    "next_billing_date": "2024-02-01T00:00:00Z"
  }
}

Purchase Credits

POST /billing/credits/purchase

Request Body:

{
  "credit_package": "professional_500",
  "payment_method_id": "pm_123456789",
  "quantity": 1
}

Response:

{
  "success": true,
  "data": {
    "transaction_id": "txn_987654321",
    "credits_purchased": 500,
    "amount": 149.99,
    "currency": "USD",
    "payment_status": "completed",
    "new_balance": 1320
  },
  "message": "Credits purchased successfully"
}

Get Billing History

GET /billing/history

Query Parameters:

  • limit: Number of results (default: 20, max: 100)
  • offset: Pagination offset (default: 0)
  • start_date: ISO 8601 date string
  • end_date: ISO 8601 date string

Response:

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn_987654321",
        "type": "credit_purchase",
        "amount": 149.99,
        "currency": "USD",
        "credits": 500,
        "status": "completed",
        "created_at": "2024-01-01T10:00:00Z",
        "description": "Professional 500 Credit Package"
      }
    ],
    "pagination": {
      "total": 15,
      "limit": 20,
      "offset": 0,
      "has_more": false
    }
  }
}

Webhook Endpoints

Create Webhook

POST /webhooks

Request Body:

{
  "url": "https://your-app.com/webhooks/mindpeeker",
  "events": [
    "session.completed",
    "session.failed",
    "analysis.ready"
  ],
  "secret": "your_webhook_secret",
  "active": true,
  "description": "Production webhook for session notifications"
}

Response:

{
  "success": true,
  "data": {
    "id": "webhook_123456789",
    "url": "https://your-app.com/webhooks/mindpeeker",
    "events": [
      "session.completed",
      "session.failed",
      "analysis.ready"
    ],
    "active": true,
    "secret": "whsec_1234567890abcdef",
    "created_at": "2024-01-01T10:00:00Z"
  },
  "message": "Webhook created successfully"
}

List Webhooks

GET /webhooks

Response:

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "webhook_123456789",
        "url": "https://your-app.com/webhooks/mindpeeker",
        "events": ["session.completed", "session.failed"],
        "active": true,
        "created_at": "2024-01-01T10:00:00Z",
        "last_triggered": "2024-01-01T09:45:00Z"
      }
    ]
  }
}

Update Webhook

PUT /webhooks/{webhook_id}

Request Body:

{
  "events": [
    "session.completed",
    "session.failed",
    "analysis.ready",
    "billing.payment_succeeded"
  ],
  "active": false
}

Response:

{
  "success": true,
  "data": {
    "id": "webhook_123456789",
    "events": [
      "session.completed",
      "session.failed",
      "analysis.ready",
      "billing.payment_succeeded"
    ],
    "active": false
  },
  "message": "Webhook updated successfully"
}

Delete Webhook

DELETE /webhooks/{webhook_id}

Response:

{
  "success": true,
  "message": "Webhook deleted successfully"
}

Admin Endpoints

Get System Status

GET /admin/system/status

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2024-01-01T10:00:00Z",
    "services": {
      "api": "healthy",
      "database": "healthy",
      "cache": "healthy",
      "ai_models": "healthy",
      "queue": "healthy"
    },
    "metrics": {
      "active_sessions": 234,
      "queue_depth": 45,
      "cpu_usage": 0.65,
      "memory_usage": 0.78,
      "gpu_usage": 0.82
    },
    "version": "2.1.0"
  }
}

Get User Analytics

GET /admin/analytics/users

Query Parameters:

  • period: day, week, month, year
  • tier: basic, professional, enterprise

Response:

{
  "success": true,
  "data": {
    "period": "month",
    "total_users": 15420,
    "active_users": 8750,
    "new_users": 1250,
    "retention_rate": 0.87,
    "tier_distribution": {
      "basic": 6540,
      "professional": 7850,
      "enterprise": 1030
    },
    "geographic_distribution": [
      {
        "country": "United States",
        "users": 5420,
        "percentage": 0.351
      }
    ]
  }
}

Error Responses

Standard Error Format

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "The provided credentials are invalid",
    "details": {
      "field": "password",
      "reason": "Password does not match"
    },
    "timestamp": "2024-01-01T10:00:00Z",
    "request_id": "req_123456789"
  }
}

Common Error Codes

Authentication Errors

  • INVALID_CREDENTIALS: Invalid email or password
  • TOKEN_EXPIRED: JWT token has expired
  • TOKEN_INVALID: JWT token is invalid
  • INSUFFICIENT_PERMISSIONS: User lacks required permissions

Validation Errors

  • INVALID_REQUEST_BODY: Request body is malformed
  • MISSING_REQUIRED_FIELD: Required field is missing
  • INVALID_FIELD_VALUE: Field value is invalid
  • FIELD_TOO_LONG: Field exceeds maximum length

Business Logic Errors

  • INSUFFICIENT_CREDITS: User has insufficient credits
  • SESSION_NOT_FOUND: Session does not exist
  • SESSION_ALREADY_COMPLETED: Session cannot be modified
  • RATE_LIMIT_EXCEEDED: API rate limit exceeded

System Errors

  • SERVICE_UNAVAILABLE: Service is temporarily unavailable
  • DATABASE_ERROR: Database operation failed
  • AI_MODEL_ERROR: AI model processing failed
  • INTERNAL_SERVER_ERROR: Unexpected server error

HTTP Status Codes

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict
  • 422 Unprocessable Entity: Validation error
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error
  • 503 Service Unavailable: Service unavailable

This comprehensive API reference provides all the endpoints needed to integrate with the MindPeeker platform effectively. Each endpoint includes detailed request/response examples and error handling information.

Technical Specifications

Comprehensive technical specifications for MindPeeker platform integration and deployment

Data Models & Schemas

Complete data models and schema definitions for MindPeeker platform