API Overview

Users

Manage user records and view onboarding progress.

• GET /api/users List all users with metadata.
  Call API Open UI
• POST /api/users Create a new user by email.
  UI form
• POST /api/users/anonymous Create an anonymous user with a randomly generated email (user_MMDDHHMMSS@xxxx.com).
  Call API

Survey questions

Explore the required demographic baseline questions and user progress.

• GET /api/survey-questions/baseline-questions Retrieve all baseline questions and options.
  Call API
• GET /api/survey-questions/pending?user_id=<id> Return unanswered question IDs grouped into baseline, all respondents, and specific respondents.
  Call API
• GET /api/survey-questions/pending/by-category?user_id=<id>&category=<label> Retrieve unanswered questions for a respondent limited to the normalized category.
  Call API
• GET /api/survey-questions/next?user_id=<id> Get the next prioritized unanswered question for a user (specific → baseline → general).
  Call API
• GET /api/survey-questions/<question_id> Retrieve the full question payload for a single question.
  Call API
• POST /api/survey-questions/lookup Submit a JSON body with { "question_id": <int> } to retrieve details.
  Open UI

Prediction prompts

Generate LLM-backed response rankings for outstanding survey questions.

Question generate

Produce predictive survey questions from arbitrary focus text using structured responses.

• POST /api/question-generate Submit { "focus_text": "..." } to receive three diagnostic survey questions.
  Call API Open UI
• POST /api/question-generate/<user_id> Generate personalized follow-up questions for a respondent by ID, falling back to exploration when no prediction errors are found.
  Open demo
• POST /api/question-generate/upload Persist a question object with answer options into the database.
  View payload format

User responses

Record and maintain answers submitted by users.

• POST /api/responses Submit {"user_id", "question_id", "option_id", "question_category"} to capture or update an answer. Category is REQUIRED.
  Open UI

• ⚠️ BREAKING CHANGE: The question_category field is now REQUIRED. Requests without this field will return HTTP 400 Bad Request.

• Request Body Examples

  // ✅ CORRECT - Profile question
  {
    "user_id": 123,
    "question_id": 5,
    "option_id": 42,
    "question_category": "profile"
  }
  
  // ✅ CORRECT - Seating preference question
  {
    "user_id": 123,
    "question_id": 1,
    "option_id": 11,
    "question_category": "seating"
  }
  
  // ✅ CORRECT - Finance attitude question
  {
    "user_id": 123,
    "question_id": 201,
    "option_id": 2015,
    "question_category": "finance"
  }
  
  // ✅ CORRECT - Technology opinion question
  {
    "user_id": 123,
    "question_id": 301,
    "option_id": 3022,
    "question_category": "technology"
  }
  
  // ❌ INCORRECT - Missing category (will fail with 400)
  {
    "user_id": 123,
    "question_id": 5,
    "option_id": 42
    // ERROR: Missing question_category
  }

  Validation Error Response

  // HTTP 400 Bad Request
  {
    "error": "question_category is required and must be a non-empty string"
  }

  Common Categories:

  • seating - Initial seating/placement questions
  • profile - General profile-building questions
  • finance - Financial attitudes and behaviors
  • technology - Technology usage and opinions
  • attitudes_about_money - Money-related beliefs
  • lifestyle - Lifestyle choices and habits
  • prediction - Prediction game questions

  Categories are normalized to lowercase with spaces replaced by underscores.

• GET /api/users/<user_id>/responses Return every question, option list, and the user’s selected response.
  Call API

Pinecone configuration

View the current Pinecone namespace used for vector store isolation.

• GET /api/pinecone-details/current-namespace Retrieve the active namespace for Pinecone vector operations.
  Call API

System health

Monitor service readiness and infrastructure seeding.

• GET /health Basic liveness check.
  Call API
• GET /health/ping Simple ping health check - returns immediate pong response.
  Call API

System status

Monitor active users and prediction generation activity in real-time.

Prediction accuracy

Evaluate how accurately the system predicts user responses by comparing predictions against actual survey answers.

Digital Twin Training

Trigger background training processes to update user digital twins with new responses and predictions. Every run is now persisted in the training_sessions table so the platform can survive restarts, monitor progress, and audit history.

# Start training
curl -X POST http://localhost:5000/api/training/start \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"user_id": 42}'

# Check status
curl http://localhost:5000/api/training/status/42 \
  -H "X-API-Key: your_api_key"

# Stop training
curl -X POST http://localhost:5000/api/training/stop \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"user_id": 42}'

# List all active trainings
curl http://localhost:5000/api/training/active \
  -H "X-API-Key: your_api_key"

// Start training
async function startTraining(userId) {
  const response = await fetch('/api/training/start', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your_api_key'
    },
    body: JSON.stringify({ user_id: userId })
  });
  
  const data = await response.json();
  
  if (response.ok) {
    console.log('Training started: session', data.session?.session_id, 'pid:', data.session?.pid);
    // Start polling for completion
    pollTrainingStatus(userId);
  } else {
    console.error('Failed to start training:', data.error);
  }
}

// Poll status every 10 seconds
async function pollTrainingStatus(userId) {
  const interval = setInterval(async () => {
    const response = await fetch(`/api/training/status/${userId}`, {
      headers: { 'X-API-Key': 'your_api_key' }
    });
    const data = await response.json();
    
    if (data.status === 'not_running') {
      clearInterval(interval);
      console.log('Training completed for user', userId);
    } else if (data.session) {
      console.log('Training still running...', 'session', data.session.session_id, 'pid:', data.session.pid);
    }
  }, 10000);
  
  // Auto-stop polling after 5 minutes
  setTimeout(() => clearInterval(interval), 300000);
}

function TrainingButton({ userId, apiKey }) {
  const [session, setSession] = React.useState(null);
  const [isTraining, setIsTraining] = React.useState(false);
  
  React.useEffect(() => {
    let interval;
    if (isTraining) {
      interval = setInterval(async () => {
        const res = await fetch(`/api/training/status/${userId}`, {
          headers: { 'X-API-Key': apiKey }
        });
        const data = await res.json();
        setSession(data.session ?? null);
        
        if (data.status === 'not_running') {
          setIsTraining(false);
        }
      }, 10000);
    }
    return () => clearInterval(interval);
  }, [isTraining, userId, apiKey]);
  
  const startTraining = async () => {
    const res = await fetch('/api/training/start', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiKey
      },
      body: JSON.stringify({ user_id: userId })
    });
    
    if (res.ok) {
      setIsTraining(true);
    }
  };
  
  return (
    <div>
      <button onClick={startTraining} disabled={isTraining}>
        {isTraining ? 'Training...' : 'Start Training'}
      </button>
      {session ? (
        <p>Session #{session.session_id} — {session.status} (pid: {session.pid ?? 'n/a'})</p>
      ) : (
        <p>No active session</p>
      )}
    </div>
  );
}