> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jobhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 05 api documentation

# API Documentation

## Overview

JobHive provides a comprehensive RESTful API built with Django REST Framework. The API supports all platform features including interview management, AI analysis, user management, and billing operations.

## Base Information

**API Base URL**: `https://api.jobhive.com/api/v1/`\
**Authentication**: JWT Bearer Token\
**Content Type**: `application/json`\
**API Version**: v1

## Authentication

### JWT Token Authentication

All API endpoints require authentication using JWT tokens.

```bash theme={null}
# Login to obtain tokens
POST /api/auth/login/
Content-Type: application/json

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

# Response
{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "user123",
    "role": "employer"
  }
}
```

### Using Authentication Tokens

```bash theme={null}
# Include token in Authorization header
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
```

### Token Refresh

```bash theme={null}
POST /api/auth/token/refresh/
Content-Type: application/json

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
```

## Core API Endpoints

### 1. User Management

#### Get Current User Profile

```bash theme={null}
GET /api/users/me/
Authorization: Bearer {token}

# Response
{
  "id": 1,
  "username": "johndoe",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "role": "employer",
  "is_verified": true,
  "created_at": "2024-01-15T10:30:00Z",
  "avatar": "https://jobhive.s3.amazonaws.com/avatars/user1.jpg",
  "social_links": {
    "linkedin": "https://linkedin.com/in/johndoe",
    "github": "https://github.com/johndoe"
  }
}
```

#### Update User Profile

```bash theme={null}
PUT /api/users/me/
Authorization: Bearer {token}
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Smith",
  "social_links": {
    "linkedin": "https://linkedin.com/in/johnsmith"
  }
}
```

#### User Registration

```bash theme={null}
POST /api/auth/register/
Content-Type: application/json

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "securepassword123",
  "first_name": "New",
  "last_name": "User",
  "role": "user"
}

# Response
{
  "user": {
    "id": 2,
    "username": "newuser",
    "email": "newuser@example.com",
    "role": "user"
  },
  "message": "Registration successful. Please verify your email."
}
```

### 2. Interview Management

#### Create Interview Session

```bash theme={null}
POST /api/interview/interviews/
Authorization: Bearer {token}
Content-Type: application/json

{
  "job_id": 123,
  "scheduled_time": "2024-02-15T14:00:00Z",
  "max_duration_minutes": 30,
  "is_practice": false,
  "enable_behavioral_analysis": true
}

# Response
{
  "id": 456,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "job": {
    "id": 123,
    "title": "Senior Software Engineer",
    "company": "TechCorp Inc."
  },
  "user_id": 1,
  "status": "scheduled",
  "scheduled_time": "2024-02-15T14:00:00Z",
  "max_duration_minutes": 30,
  "is_practice": false,
  "created_at": "2024-02-10T09:00:00Z"
}
```

#### Get Interview Sessions

```bash theme={null}
GET /api/interview/interviews/
Authorization: Bearer {token}

# Query Parameters
# ?status=completed&limit=10&offset=0&ordering=-start_time

# Response
{
  "count": 25,
  "next": "https://api.jobhive.com/api/interview/interviews/?offset=10",
  "previous": null,
  "results": [
    {
      "id": 456,
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "job": {
        "id": 123,
        "title": "Senior Software Engineer",
        "company": "TechCorp Inc."
      },
      "status": "completed",
      "start_time": "2024-02-15T14:00:00Z",
      "end_time": "2024-02-15T14:35:00Z",
      "duration": 2100.5,
      "completion_percentage": 85,
      "technical_accuracy": 78.5,
      "behavioral_score": 82.3
    }
  ]
}
```

#### Get Interview Details

```bash theme={null}
GET /api/interview/interviews/{interview_id}/
Authorization: Bearer {token}

# Response
{
  "id": 456,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "job": {
    "id": 123,
    "title": "Senior Software Engineer",
    "company": "TechCorp Inc.",
    "requirements": "Python, Django, REST APIs, PostgreSQL"
  },
  "user": {
    "id": 1,
    "username": "johndoe",
    "email": "john@example.com"
  },
  "status": "completed",
  "start_time": "2024-02-15T14:00:00Z",
  "end_time": "2024-02-15T14:35:00Z",
  "duration": 2100.5,
  "completion_percentage": 85,
  "technical_accuracy": 78.5,
  "behavioral_score": 82.3,
  "is_practice": false,
  "response_times": [12.5, 8.3, 15.7, 9.2],
  "attention_metrics": {
    "focus_scores": [0.85, 0.92, 0.78, 0.88],
    "engagement_level": 0.86
  }
}
```

#### Update Interview Session

```bash theme={null}
PUT /api/interview/interviews/{interview_id}/
Authorization: Bearer {token}
Content-Type: application/json

{
  "interviewer_notes": "Candidate showed strong technical skills but needs improvement in system design.",
  "status": "completed"
}
```

#### End Interview Session

```bash theme={null}
POST /api/interview/interviews/{interview_id}/end_session/
Authorization: Bearer {token}

# Response
{
  "id": 456,
  "status": "completed",
  "end_time": "2024-02-15T14:35:00Z",
  "duration": 2100.5,
  "completion_percentage": 85,
  "message": "Interview session ended successfully"
}
```

### 3. AI Analysis & Scoring

#### Get Benchmark Comparison

```bash theme={null}
GET /api/interview/interviews/{interview_id}/benchmark-comparison/
Authorization: Bearer {token}

# Response
{
  "met_requirements": [
    {
      "skill": "python",
      "score": 8.5,
      "percentile": 78,
      "proficiency_level": "Proficient",
      "importance_weight": 1.2,
      "threshold": 7.5
    }
  ],
  "below_requirements": [
    {
      "skill": "system design",
      "score": 6.2,
      "gap": 1.3,
      "proficiency_level": "Developing",
      "importance_weight": 1.5,
      "threshold": 7.5
    }
  ],
  "score_percentile": 72,
  "industry_percentile": 68,
  "skill_breakdown": [
    {
      "skill": "python",
      "score": 8.5,
      "is_required": true,
      "weight": 1.2,
      "proficiency_level": "Proficient",
      "job_relevance": "High"
    }
  ],
  "improvement_areas": [
    {
      "skill": "system design",
      "current_score": 6.2,
      "target_score": 7.5,
      "gap": 1.3,
      "priority": "High",
      "importance_weight": 1.5
    }
  ],
  "strengths": [
    {
      "skill": "python",
      "score": 8.5,
      "importance_weight": 1.2
    }
  ]
}
```

#### Get Sentiment Analysis

```bash theme={null}
GET /api/interview/sentiment-sessions/
Authorization: Bearer {token}

# Query Parameters
# ?interview_session=456

# Response
{
  "count": 1,
  "results": [
    {
      "id": 789,
      "interview_session": 456,
      "overall_sentiment": "Positive",
      "positive_score": 0.75,
      "negative_score": 0.15,
      "neutral_score": 0.08,
      "mixed_score": 0.02,
      "confidence_level": 0.82,
      "engagement_score": 0.78,
      "professionalism_score": 0.85,
      "clarity_score": 0.79,
      "created_at": "2024-02-15T14:35:00Z"
    }
  ]
}
```

#### Get Skill Assessments

```bash theme={null}
GET /api/interview/skill-assessments/
Authorization: Bearer {token}

# Query Parameters
# ?interview_session=456

# Response
{
  "count": 5,
  "results": [
    {
      "id": 101,
      "interview_session": 456,
      "skill": {
        "id": 1,
        "name": "Communication",
        "category": "Soft Skills"
      },
      "accumulated_score": 8.5,
      "update_count": 3,
      "history": [
        {
          "id": 201,
          "score": 2.5,
          "timestamp": "2024-02-15T14:10:00Z"
        },
        {
          "id": 202,
          "score": 3.0,
          "timestamp": "2024-02-15T14:20:00Z"
        },
        {
          "id": 203,
          "score": 3.0,
          "timestamp": "2024-02-15T14:30:00Z"
        }
      ]
    }
  ]
}
```

#### Get Score Weights

```bash theme={null}
GET /api/interview/score-weights/
Authorization: Bearer {token}

# Query Parameters
# ?job_focus=technical

# Response
{
  "count": 1,
  "results": [
    {
      "id": 1,
      "job_focus": "technical",
      "technical_weight": 0.40,
      "skills_weight": 0.30,
      "cultural_fit_weight": 0.20,
      "sentiment_weight": 0.10
    }
  ]
}
```

### 4. Recommendations & Learning

#### Get Recommendations

```bash theme={null}
GET /api/interview/recommendations/
Authorization: Bearer {token}

# Query Parameters
# ?interview_session=456

# Response
{
  "count": 3,
  "results": [
    {
      "id": 301,
      "interview_session": 456,
      "skill": {
        "id": 5,
        "name": "System Design"
      },
      "recommendation_text": "Focus on scalability patterns and distributed systems design. Practice with system design interviews and study microservices architecture.",
      "feedback_type": "improvement",
      "feedback_category": "technical",
      "created_at": "2024-02-15T14:35:00Z"
    }
  ]
}
```

#### Get Learning Paths

```bash theme={null}
GET /api/interview/learning-paths/
Authorization: Bearer {token}

# Query Parameters
# ?interview_session=456

# Response
{
  "count": 1,
  "results": [
    {
      "id": 401,
      "interview_session": 456,
      "status": "active",
      "created_at": "2024-02-15T14:35:00Z",
      "resources": [
        {
          "id": 501,
          "title": "System Design Fundamentals",
          "resource_type": "course",
          "url": "https://example.com/system-design-course",
          "estimated_hours": 20,
          "order": 1,
          "completed": false
        },
        {
          "id": 502,
          "title": "Microservices Architecture Patterns",
          "resource_type": "book",
          "url": "https://example.com/microservices-book",
          "estimated_hours": 15,
          "order": 2,
          "completed": false
        }
      ]
    }
  ]
}
```

### 5. Job Management

#### Get Job Listings

```bash theme={null}
GET /api/interview/jobs/
Authorization: Bearer {token}

# Query Parameters
# ?company=123&is_active=true&limit=20

# Response
{
  "count": 15,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 123,
      "title": "Senior Software Engineer",
      "description": "We are looking for an experienced software engineer...",
      "requirements": "Python, Django, REST APIs, PostgreSQL, 5+ years experience",
      "company": {
        "id": 45,
        "company_name": "TechCorp Inc.",
        "industry": "Technology"
      },
      "job_focus": "technical",
      "is_active": true,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}
```

#### Create Job Posting

```bash theme={null}
POST /api/interview/jobs/
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Frontend Developer",
  "description": "We are seeking a talented Frontend Developer to join our team...",
  "requirements": "React, TypeScript, CSS, HTML, 3+ years experience",
  "job_focus": "technical",
  "is_active": true
}

# Response
{
  "id": 124,
  "title": "Frontend Developer",
  "description": "We are seeking a talented Frontend Developer to join our team...",
  "requirements": "React, TypeScript, CSS, HTML, 3+ years experience",
  "company": {
    "id": 45,
    "company_name": "TechCorp Inc."
  },
  "job_focus": "technical",
  "is_active": true,
  "created_at": "2024-02-10T15:30:00Z"
}
```

### 6. Billing & Subscriptions

#### Get Subscription Plans

```bash theme={null}
GET /api/billing/plans/
Authorization: Bearer {token}

# Query Parameters
# ?plan_type=employer&is_active=true

# Response
{
  "count": 3,
  "results": [
    {
      "id": 1,
      "name": "Starter Employer",
      "description": "Perfect for small businesses",
      "plan_type": "employer",
      "interval": "month",
      "price": "99.99",
      "interview_limit": 10,
      "job_posting_limit": 5,
      "application_limit": 100,
      "features": ["basic_analytics", "team_collaboration"],
      "sort_order": 1,
      "is_active": true
    }
  ]
}
```

#### Get User Subscription

```bash theme={null}
GET /api/billing/subscriptions/
Authorization: Bearer {token}

# Response
{
  "id": 678,
  "user": 1,
  "plan": {
    "id": 1,
    "name": "Starter Employer",
    "price": "99.99"
  },
  "status": "active",
  "start_date": "2024-01-01T00:00:00Z",
  "current_period_start": "2024-02-01T00:00:00Z",
  "current_period_end": "2024-03-01T00:00:00Z",
  "cancel_at_period_end": false,
  "stripe_subscription_id": "sub_1234567890",
  "created_at": "2024-01-01T00:00:00Z"
}
```

#### Create Subscription

```bash theme={null}
POST /api/billing/subscriptions/
Authorization: Bearer {token}
Content-Type: application/json

{
  "plan_id": 2,
  "payment_method_id": "pm_1234567890"
}

# Response
{
  "id": 679,
  "plan": {
    "id": 2,
    "name": "Business Employer",
    "price": "249.99"
  },
  "status": "active",
  "stripe_subscription_id": "sub_0987654321",
  "message": "Subscription created successfully"
}
```

#### Get Billing Analytics

```bash theme={null}
GET /api/billing/analytics/
Authorization: Bearer {token}

# Response
{
  "current_period": {
    "start_date": "2024-02-01T00:00:00Z",
    "end_date": "2024-03-01T00:00:00Z",
    "interviews_used": 7,
    "interviews_limit": 10,
    "job_postings_used": 3,
    "job_postings_limit": 5
  },
  "usage_trends": [
    {
      "date": "2024-02-01",
      "interviews": 2,
      "applications": 15
    },
    {
      "date": "2024-02-02",
      "interviews": 1,
      "applications": 8
    }
  ],
  "feature_access": {
    "advanced_analytics": true,
    "team_collaboration": true,
    "api_access": false
  }
}
```

### 7. Analytics & Reporting

#### Get Interview Analytics

```bash theme={null}
GET /api/interview/analytics/
Authorization: Bearer {token}

# Query Parameters
# ?start_date=2024-01-01&end_date=2024-02-29&company_id=45

# Response
{
  "summary": {
    "total_interviews": 25,
    "completed_interviews": 23,
    "average_score": 76.5,
    "average_duration": 1845.2,
    "completion_rate": 92.0
  },
  "trends": [
    {
      "date": "2024-02-01",
      "interviews": 3,
      "avg_score": 78.5,
      "completion_rate": 100.0
    },
    {
      "date": "2024-02-02",
      "interviews": 2,
      "avg_score": 74.2,
      "completion_rate": 85.0
    }
  ],
  "skill_distribution": [
    {
      "skill": "Communication",
      "average_score": 8.2,
      "total_assessments": 23
    },
    {
      "skill": "Technical Skills",
      "average_score": 7.8,
      "total_assessments": 23
    }
  ]
}
```

#### Get Historical Trends

```bash theme={null}
GET /api/interview/reports/historical_trends/{user_id}/
Authorization: Bearer {token}

# Response
{
  "user_id": 1,
  "trends": [
    {
      "date": "2024-01-15",
      "interview_id": 440,
      "overall_score": 72.5,
      "technical_score": 75.0,
      "behavioral_score": 70.0,
      "skills": {
        "Communication": 8.0,
        "Problem Solving": 7.5,
        "Technical Knowledge": 7.8
      }
    },
    {
      "date": "2024-02-15",
      "interview_id": 456,
      "overall_score": 85.0,
      "technical_score": 87.2,
      "behavioral_score": 82.8,
      "skills": {
        "Communication": 8.5,
        "Problem Solving": 8.7,
        "Technical Knowledge": 8.9
      }
    }
  ],
  "summary": {
    "total_interviews": 2,
    "improvement_rate": 17.2,
    "strongest_skill": "Technical Knowledge",
    "most_improved_skill": "Problem Solving"
  }
}
```

## Error Handling

### Standard Error Response Format

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field_name": ["This field is required."],
      "another_field": ["This field must be unique."]
    },
    "timestamp": "2024-02-15T14:30:00Z",
    "request_id": "req_123456789"
  }
}
```

### Common HTTP Status Codes

| Status Code | Description           | Usage                                 |
| ----------- | --------------------- | ------------------------------------- |
| 200         | OK                    | Successful GET, PUT requests          |
| 201         | Created               | Successful POST requests              |
| 204         | No Content            | Successful DELETE requests            |
| 400         | Bad Request           | Validation errors, malformed requests |
| 401         | Unauthorized          | Missing or invalid authentication     |
| 403         | Forbidden             | Insufficient permissions              |
| 404         | Not Found             | Resource doesn't exist                |
| 409         | Conflict              | Resource conflict (e.g., duplicate)   |
| 429         | Too Many Requests     | Rate limit exceeded                   |
| 500         | Internal Server Error | Server-side errors                    |

### Error Code Reference

| Error Code                | Description                          |
| ------------------------- | ------------------------------------ |
| `VALIDATION_ERROR`        | Input validation failed              |
| `AUTHENTICATION_REQUIRED` | Valid authentication token required  |
| `PERMISSION_DENIED`       | Insufficient permissions for action  |
| `RESOURCE_NOT_FOUND`      | Requested resource doesn't exist     |
| `DUPLICATE_RESOURCE`      | Resource already exists              |
| `RATE_LIMIT_EXCEEDED`     | API rate limit exceeded              |
| `SUBSCRIPTION_REQUIRED`   | Feature requires active subscription |
| `INTERVIEW_IN_PROGRESS`   | Cannot modify active interview       |

## Rate Limiting

### Rate Limit Headers

```bash theme={null}
X-RateLimit-Limit: 1000        # Requests per hour
X-RateLimit-Remaining: 999     # Remaining requests
X-RateLimit-Reset: 1645123456  # Reset timestamp
```

### Rate Limits by Endpoint Category

| Endpoint Category    | Rate Limit    | Window     |
| -------------------- | ------------- | ---------- |
| Authentication       | 20 requests   | 15 minutes |
| Interview Management | 100 requests  | 1 hour     |
| AI Analysis          | 50 requests   | 1 hour     |
| Analytics            | 200 requests  | 1 hour     |
| General API          | 1000 requests | 1 hour     |

## Pagination

### Standard Pagination Format

```json theme={null}
{
  "count": 150,
  "next": "https://api.jobhive.com/api/endpoint/?offset=20&limit=20",
  "previous": "https://api.jobhive.com/api/endpoint/?offset=0&limit=20",
  "results": [
    // ... array of results
  ]
}
```

### Pagination Parameters

* `limit`: Number of results per page (default: 20, max: 100)
* `offset`: Number of results to skip
* `ordering`: Sort field (use `-` prefix for descending)

## WebSocket API

### Connection

```javascript theme={null}
const socket = new WebSocket('wss://api.jobhive.com/ws/interview/456/');

socket.onopen = function(event) {
  console.log('Connected to interview session');
};

socket.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);
};
```

### Message Types

```json theme={null}
// Real-time sentiment update
{
  "type": "sentiment_update",
  "data": {
    "positive_score": 0.75,
    "engagement_score": 0.82,
    "timestamp": "2024-02-15T14:25:00Z"
  }
}

// Skill assessment update
{
  "type": "skill_update",
  "data": {
    "skill": "Communication",
    "score": 8.5,
    "timestamp": "2024-02-15T14:25:00Z"
  }
}

// Interview status change
{
  "type": "status_change",
  "data": {
    "status": "completed",
    "completion_percentage": 85,
    "timestamp": "2024-02-15T14:35:00Z"
  }
}
```

## SDK Examples

### Python SDK

```python theme={null}
import jobhive

# Initialize client
client = jobhive.Client(api_key='your_api_key')

# Create interview session
interview = client.interviews.create(
    job_id=123,
    scheduled_time='2024-02-15T14:00:00Z',
    max_duration_minutes=30
)

# Get real-time updates
def handle_update(update):
    print(f"Received update: {update}")

client.interviews.subscribe(interview.id, handle_update)
```

### JavaScript SDK

```javascript theme={null}
import JobHive from 'jobhive-js';

// Initialize client
const client = new JobHive({ apiKey: 'your_api_key' });

// Create interview session
const interview = await client.interviews.create({
  jobId: 123,
  scheduledTime: '2024-02-15T14:00:00Z',
  maxDurationMinutes: 30
});

// Get benchmark comparison
const benchmark = await client.interviews.getBenchmarkComparison(interview.id);
console.log('Benchmark data:', benchmark);
```

## Testing & Development

### Sandbox Environment

**Base URL**: `https://sandbox-api.jobhive.com/api/v1/`\
**Test Cards**: Use Stripe test card numbers for billing tests

### API Testing Tools

* **Postman Collection**: Available for download
* **OpenAPI Specification**: Swagger documentation at `/api/docs/`
* **Interactive Testing**: Available at `/api/playground/`

### Webhook Testing

```bash theme={null}
# Test webhook endpoint
POST /api/webhooks/test/
Authorization: Bearer {token}

{
  "event_type": "interview.completed",
  "data": {
    "interview_id": 456,
    "status": "completed"
  }
}
```