behavior_api_endpoints.txt

# Behavior Analytics API Documentation

## Base URL
All endpoints are prefixed with `/api` unless specified otherwise.

## Authentication Endpoints

### 1. OAuth2 Login
- **URL**: `/api/auth/login`
- **Method**: POST
- **Input**:
```json
{
  "username": "user@example.com",
  "password": "yourpassword"
}
```
- **Output**:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

### 2. Email Login
- **URL**: `/api/auth/login/email`
- **Method**: POST
- **Input**:
```json
{
  "email": "user@example.com",
  "password": "yourpassword"
}
```
- **Output**:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

### 3. Refresh Token
- **URL**: `/api/auth/refresh`
- **Method**: POST
- **Input**: None (requires authenticated request with valid token)
- **Output**:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

## User Endpoints

### 1. Create User
- **URL**: `/api/users/`
- **Method**: POST
- **Input**:
```json
{
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "password": "securepassword"
}
```
- **Output**:
```json
{
  "id": "uuid-string",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2023-01-01T12:00:00.000Z",
  "is_active": true
}
```

### 2. Get Current User
- **URL**: `/api/users/me`
- **Method**: GET
- **Input**: None (requires authenticated request)
- **Output**:
```json
{
  "id": "uuid-string",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2023-01-01T12:00:00.000Z",
  "is_active": true
}
```

### 3. Get User by ID
- **URL**: `/api/users/{user_id}`
- **Method**: GET
- **Input**: None (requires authenticated request)
- **Output**:
```json
{
  "id": "uuid-string",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2023-01-01T12:00:00.000Z",
  "is_active": true
}
```

## Video Endpoints

### 1. Upload Video (Direct)
- **URL**: `/api/videos/upload-direct`
- **Method**: POST
- **Input**: Multipart form data with file field
- **Headers**: X-API-Key: your-api-key
- **Output**:
```json
{
  "video_id": "vid-12345",
  "original_filename": "example.mp4",
  "upload_date": "2023-01-01T12:00:00.000Z",
  "size": 12345678,
  "status": "uploaded",
  "duration": 120.5,
  "video_url": "/uploads/vid-12345.mp4"
}
```

### 2. Upload and Process Video (Direct)
- **URL**: `/api/videos/upload-and-process-direct`
- **Method**: POST
- **Input**: Multipart form data with following fields:
  - file: The video file
  - frame_rate: integer (default 35)
  - language: string (default "en")
  - backend: string (default "mediapipe")
  - generate_annotated_video: boolean (default false)
  - model_name: string (default "gpt-4o")
- **Headers**: X-API-Key: your-api-key
- **Output**:
```json
{
  "video_id": "vid-12345",
  "processing_results": {
    "emotion_data": {},
    "transcript": "transcribed text...",
    "analysis": "analysis text...",
    "annotated_video_available": false,
    "emotion_percentages": {},
    "overall_sentiment": "positive",
    "frame_emotions_count": 120,
    "overall_summary": "summary text...",
    "transcript_analysis": {},
    "recommendations": {},
    "body_language_analysis": {},
    "body_language_data": {},
    "eye_contact_analysis": {},
    "eye_contact_data": {}
  },
  "timing": {
    "upload_time": 1.23,
    "processing_time": 45.67,
    "total_time": 46.9
  }
}
```

## Processing Endpoints

### 1. Process Video
- **URL**: `/api/processing/direct`
- **Method**: POST
- **Input**:
```json
{
  "video_id": "vid-12345",
  "frame_rate": 5,
  "language": "en",
  "backend": "opencv",
  "generate_annotated_video": false,
  "model_name": "gpt-4o"
}
```
- **Headers**: X-API-Key: your-api-key
- **Output**:
```json
{
  "video_id": "vid-12345",
  "status": "processing",
  "progress": 0
}
```

### 2. Get Processing Status
- **URL**: `/api/processing/direct/status/{video_id}`
- **Method**: GET
- **Headers**: X-API-Key: your-api-key
- **Output**:
```json
{
  "video_id": "vid-12345",
  "status": "completed",
  "progress": 100,
  "error": null
}
```

### 3. Get Processing Results
- **URL**: `/api/processing/direct/results/{video_id}`
- **Method**: GET
- **Headers**: X-API-Key: your-api-key
- **Output**:
```json
{
  "video_id": "vid-12345",
  "emotion_data": {
    "face_1": [
      {
        "frame": 0,
        "emotions": {
          "happy": 0.8,
          "sad": 0.1,
          "angry": 0.05,
          "surprised": 0.05
        },
        "timestamp": 0.0
      }
    ]
  },
  "transcript": "transcribed text...",
  "analysis": "analysis text...",
  "annotated_video_available": false,
  "emotion_percentages": {
    "happy": 75,
    "sad": 15,
    "angry": 5,
    "surprised": 5
  },
  "overall_sentiment": "positive",
  "frame_emotions_count": 120,
  "overall_summary": "summary text...",
  "transcript_analysis": {
    "key_points": ["point 1", "point 2"],
    "sentiment": "positive"
  },
  "recommendations": {
    "improvements": ["suggestion 1", "suggestion 2"]
  },
  "body_language_analysis": {
    "summary": "body language summary",
    "key_observations": ["observation 1", "observation 2"]
  },
  "body_language_data": {
    "timestamps": [0, 1, 2],
    "postures": ["standing", "gesturing", "seated"]
  },
  "eye_contact_analysis": {
    "summary": "eye contact summary",
    "percentage": 85
  },
  "eye_contact_data": {
    "timestamps": [0, 1, 2],
    "looking_at_camera": [true, false, true]
  }
}
```

### 4. Get Processing Results (with user authentication)
- **URL**: `/api/processing/results/{video_id}`
- **Method**: GET
- **Authorization**: Bearer token
- **Output**: Same as `/api/processing/direct/results/{video_id}`

## Health Endpoints

### 1. Simple Health Check
- **URL**: `/health`
- **Method**: GET
- **Input**: None
- **Output**:
```json
{
  "status": "ok"
}
```

### 2. API Health Check
- **URL**: `/health/api`
- **Method**: GET
- **Input**: None
- **Output**:
```json
{
  "status": "healthy",
  "database": "connected",
  "api": "running"
}
```

## Root Endpoint

### 1. Root
- **URL**: `/`
- **Method**: GET
- **Authorization**: Required (Bearer token or HF Space JWT)
- **Output**:
```json
{
  "status": "ok",
  "message": "Behavior Analytics API is running",
  "version": "1.0.0"
}
```