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.

# 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

# Include token in Authorization header
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Token Refresh

POST /api/auth/token/refresh/
Content-Type: application/json

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

Core API Endpoints

1. User Management

Get Current User Profile

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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

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

{
  "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

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

// 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

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

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

# Test webhook endpoint
POST /api/webhooks/test/
Authorization: Bearer {token}

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

Documentation Index

​API Documentation

​Overview

​Base Information

​Authentication

​JWT Token Authentication

​Using Authentication Tokens

​Token Refresh

​Core API Endpoints

​1. User Management

​Get Current User Profile

​Update User Profile

​User Registration

​2. Interview Management

​Create Interview Session

​Get Interview Sessions

​Get Interview Details

​Update Interview Session

​End Interview Session

​3. AI Analysis & Scoring

​Get Benchmark Comparison

​Get Sentiment Analysis

​Get Skill Assessments

​Get Score Weights

​4. Recommendations & Learning

​Get Recommendations

​Get Learning Paths

​5. Job Management

​Get Job Listings

​Create Job Posting

​6. Billing & Subscriptions

​Get Subscription Plans

​Get User Subscription

​Create Subscription

​Get Billing Analytics

​7. Analytics & Reporting

​Get Interview Analytics

​Get Historical Trends

​Error Handling

​Standard Error Response Format

​Common HTTP Status Codes

​Error Code Reference

​Rate Limiting

​Rate Limit Headers

​Rate Limits by Endpoint Category

​Pagination

​Standard Pagination Format

​Pagination Parameters

​WebSocket API

​Connection

​Message Types

​SDK Examples

​Python SDK

​JavaScript SDK

​Testing & Development

​Sandbox Environment

​API Testing Tools

​Webhook Testing