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.
Prerequisites :
API key from your JobHive dashboard
Node.js version 18+ (for JavaScript/TypeScript)
Python 3.10+ (for Python integrations)
Docker and Docker Compose (for local development)
PostgreSQL 14+ (for database development)
Get up and running with JobHive’s AI-powered interview platform in minutes. This guide covers both platform integration and local development setup.
Get Your API Key
Log into your JobHive dashboard
Navigate to Settings → API Keys
Generate a new API key for your application
Copy and securely store your API key
# Set your API key as environment variable
export JOBHIVE_API_KEY = "your_api_key_here"
Choose Your Development Path
Create Your First Interview
import axios from 'axios' ;
const apiClient = axios . create ({
baseURL: 'https://backend.jobhive.ai/api/v1' ,
headers: {
'Authorization' : `Bearer ${ process . env . JOBHIVE_API_KEY } ` ,
'Content-Type' : 'application/json'
}
});
const response = await apiClient . post ( '/interviews/' , {
job: {
title: "Senior Full Stack Developer" ,
description: "We're looking for an experienced developer..." ,
requirements: "5+ years experience, React, Node.js, PostgreSQL"
},
candidate_email: "candidate@example.com" ,
skills_to_assess: [ "JavaScript" , "React" , "Node.js" , "System Design" ],
duration_minutes: 60 ,
difficulty_level: "senior"
});
const interview = response . data ;
console . log ( `Interview created: ${ interview . session_id } ` );
console . log ( `Candidate link: ${ interview . candidate_link } ` );
import requests
import os
headers = {
'Authorization' : f 'Bearer { os.environ[ "JOBHIVE_API_KEY" ] } ' ,
'Content-Type' : 'application/json'
}
data = {
'job' : {
'title' : 'Senior Full Stack Developer' ,
'description' : 'We \' re looking for an experienced developer...' ,
'requirements' : '5+ years experience, React, Node.js, PostgreSQL'
},
'candidate_email' : 'candidate@example.com' ,
'skills_to_assess' : [ 'JavaScript' , 'React' , 'Node.js' , 'System Design' ],
'duration_minutes' : 60 ,
'difficulty_level' : 'senior'
}
response = requests.post(
'https://backend.jobhive.ai/api/v1/interviews/' ,
headers = headers,
json = data
)
interview = response.json()
print ( f "Interview created: { interview[ 'session_id' ] } " )
print ( f "Candidate link: { interview[ 'candidate_link' ] } " )
curl -X POST "https://backend.jobhive.ai/api/v1/interviews/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job": {
"title": "Senior Full Stack Developer",
"description": "We are looking for an experienced developer...",
"requirements": "5+ years experience, React, Node.js, PostgreSQL"
},
"candidate_email": "candidate@example.com",
"skills_to_assess": ["JavaScript", "React", "Node.js", "System Design"],
"duration_minutes": 60,
"difficulty_level": "senior"
}'
Local Development Environment
Backend Setup
Database Setup
# Start PostgreSQL with Docker
docker run --name jobhive-postgres \
-e POSTGRES_DB=jobhive_dev \
-e POSTGRES_USER=jobhive \
-e POSTGRES_PASSWORD=password \
-p 5432:5432 -d postgres:14
# Or use Docker Compose
docker-compose -f docker-compose.local.yml up postgres
Redis Setup
# Start Redis for caching and WebSockets
docker run --name jobhive-redis -p 6379:6379 -d redis:7-alpine
Environment Configuration
Create a .env.local file: # Database
DATABASE_URL = postgresql://jobhive:password@localhost/jobhive_dev
# Redis
REDIS_URL = redis://localhost:6379/0
# API Keys
OPENAI_API_KEY = your_openai_key
ANTHROPIC_API_KEY = your_anthropic_key
# AWS (for local S3-compatible storage)
AWS_ACCESS_KEY_ID = minioadmin
AWS_SECRET_ACCESS_KEY = minioadmin
AWS_STORAGE_BUCKET_NAME = jobhive-dev
AWS_S3_ENDPOINT_URL = http://localhost:9000
# Development settings
DEBUG = True
USE_TZ = True
SECRET_KEY = your-secret-key-for-development
Start Development Server
# Install dependencies
pip install -r requirements/local.txt
# Run migrations
python manage.py migrate
# Load sample data
python manage.py loaddata fixtures/sample_data.json
# Start Celery worker (in separate terminal)
celery -A config worker -l info
# Start Celery beat (in separate terminal)
celery -A config beat -l info
# Start Django server
python manage.py runserver 0.0.0.0:8000
Frontend Development
# Install dependencies for real-time interview interface
npm install axios socket.io-client react-webcam
# Example real-time interview component
import React, { useState, useEffect } from 'react' ;
import axios from 'axios' ;
import io from 'socket.io-client' ;
import Webcam from 'react-webcam' ;
function LiveInterview ({ sessionId, apiKey }) {
const [socket, setSocket] = useState ( null );
const [interviewState, setInterviewState] = useState ( null );
const [isConnected, setIsConnected] = useState ( false );
useEffect(( ) = > {
// Initialize WebSocket connection
const newSocket = io ( ` wss://backend.jobhive.ai/ws/interview/$ {sessionId} / ` , {
auth: { token: apiKey }
});
newSocket.on( 'connect' , () => {
setIsConnected(true );
});
newSocket.on( 'interview_update' , (data) = > {
setInterviewState(data );
});
newSocket.on( 'question' , (data) = > {
console.log( 'New question:' , data.question );
});
setSocket(newSocket );
return () = > newSocket.close ();
}, [sessionId, apiKey]);
const sendResponse = (response) = > {
if ( socket && isConnected ) {
socket.emit( 'candidate_response' , {
session_id: sessionId,
response: response,
timestamp: new Date () .toISOString ()
});
}
};
return (
< div className="interview-container" >
< div className="video-section" >
< Webcam
audio = { true }
width = { 640}
height = { 480}
/ >
< /div >
< div className="chat-section" >
{ interviewState?.current_question && (
< div className="question" >
< h3 > Current Question: < /h 3>
< p > {interviewState.current_question} </p>
< /div >
)}
< div className="status" >
Status: {isConnected ? 'Connected' : 'Disconnected'}
< /div >
< /div >
< /div >
);
}
Webhook Setup
Configure webhooks to receive real-time updates about interview events.
const express = require ( 'express' );
const crypto = require ( 'crypto' );
const app = express ();
app . use ( express . json ());
// Webhook signature verification
function verifyWebhookSignature ( payload , signature , secret ) {
const expectedSignature = crypto
. createHmac ( 'sha256' , secret )
. update ( payload , 'utf8' )
. digest ( 'hex' );
return crypto . timingSafeEqual (
Buffer . from ( signature ),
Buffer . from ( expectedSignature )
);
}
app . post ( '/webhooks/jobhive' , ( req , res ) => {
const signature = req . headers [ 'x-jobhive-signature' ];
const payload = JSON . stringify ( req . body );
if ( ! verifyWebhookSignature ( payload , signature , process . env . JOBHIVE_WEBHOOK_SECRET )) {
return res . status ( 401 ). send ( 'Unauthorized' );
}
const { event , data } = req . body ;
switch ( event ) {
case 'interview.completed' :
handleInterviewCompleted ( data );
break ;
case 'interview.started' :
handleInterviewStarted ( data );
break ;
case 'candidate.joined' :
handleCandidateJoined ( data );
break ;
case 'analysis.ready' :
handleAnalysisReady ( data );
break ;
}
res . status ( 200 ). send ( 'OK' );
});
function handleInterviewCompleted ( data ) {
console . log ( 'Interview completed:' , data );
// Update your database
// Send notifications
// Generate reports
}
import json
import hmac
import hashlib
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_http_methods
@csrf_exempt
@require_http_methods ([ "POST" ])
def jobhive_webhook ( request ):
# Verify webhook signature
signature = request.headers.get( 'X-JobHive-Signature' )
payload = request.body
expected_signature = hmac.new(
settings. JOBHIVE_WEBHOOK_SECRET .encode(),
payload,
hashlib.sha256
).hexdigest()
if not hmac.compare_digest(signature, expected_signature):
return HttpResponse( 'Unauthorized' , status = 401 )
data = json.loads(payload)
event = data.get( 'event' )
event_data = data.get( 'data' )
if event == 'interview.completed' :
handle_interview_completed(event_data)
elif event == 'interview.started' :
handle_interview_started(event_data)
elif event == 'analysis.ready' :
handle_analysis_ready(event_data)
return HttpResponse( 'OK' )
def handle_interview_completed ( data ):
# Process completed interview
interview_id = data[ 'interview_id' ]
results = data[ 'results' ]
# Update your models, send notifications, etc.
Environment Configuration
Development
Production
Docker Compose
# JobHive API Configuration
JOBHIVE_API_KEY = jh_dev_your_api_key_here
JOBHIVE_WEBHOOK_SECRET = whsec_your_webhook_secret
JOBHIVE_ENVIRONMENT = development
JOBHIVE_BASE_URL = https://backend.jobhive.ai/api/v1
# AI Service Configuration
OPENAI_API_KEY = sk-your-openai-key
ANTHROPIC_API_KEY = sk-ant-your-anthropic-key
# Database Configuration
DATABASE_URL = postgresql://jobhive:password@localhost/jobhive_dev
REDIS_URL = redis://localhost:6379/0
# File Storage
AWS_STORAGE_BUCKET_NAME = jobhive-dev-bucket
AWS_S3_REGION_NAME = us-east-1
# Security
SECRET_KEY = your-development-secret-key
DEBUG = True
ALLOWED_HOSTS = localhost,127.0.0.1
# JobHive API Configuration
JOBHIVE_API_KEY = jh_live_your_api_key_here
JOBHIVE_WEBHOOK_SECRET = whsec_your_webhook_secret
JOBHIVE_ENVIRONMENT = production
JOBHIVE_BASE_URL = https://backend.jobhive.ai/api/v1
# AI Service Configuration
OPENAI_API_KEY = sk-your-production-openai-key
ANTHROPIC_API_KEY = sk-ant-your-production-anthropic-key
# Database Configuration
DATABASE_URL = postgresql://username:password@db.host:5432/jobhive_prod
REDIS_URL = redis://your-redis-host:6379/0
# File Storage
AWS_STORAGE_BUCKET_NAME = jobhive-prod-bucket
AWS_S3_REGION_NAME = us-east-1
# Security
SECRET_KEY = your-production-secret-key
DEBUG = False
ALLOWED_HOSTS = yourdomain.com,api.yourdomain.com
# Monitoring
DATADOG_API_KEY = your_datadog_key
SENTRY_DSN = your_sentry_dsn
version : '3.8'
services :
web :
build : .
environment :
- DATABASE_URL=postgresql://jobhive:password@db:5432/jobhive_dev
- REDIS_URL=redis://redis:6379/0
- OPENAI_API_KEY=${OPENAI_API_KEY}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
ports :
- "8000:8000"
depends_on :
- db
- redis
db :
image : postgres:14
environment :
- POSTGRES_DB=jobhive_dev
- POSTGRES_USER=jobhive
- POSTGRES_PASSWORD=password
volumes :
- postgres_data:/var/lib/postgresql/data
redis :
image : redis:7-alpine
ports :
- "6379:6379"
celery :
build : .
command : celery -A config worker -l info
environment :
- DATABASE_URL=postgresql://jobhive:password@db:5432/jobhive_dev
- REDIS_URL=redis://redis:6379/0
depends_on :
- db
- redis
volumes :
postgres_data :
Testing Your Integration
Test Mode
Use our test mode to validate your integration without consuming credits or creating real interviews.
// Create a test interview
const response = await apiClient . post ( '/interviews/' , {
job: {
title: "Test Position" ,
description: "This is a test interview" ,
requirements: "No real requirements"
},
candidate_email: "test@example.com" ,
skills_to_assess: [ "JavaScript" , "Problem Solving" ],
test_mode: true ,
duration_minutes: 30
});
const testInterview = response . data ;
console . log ( `Test interview created: ${ testInterview . session_id } ` );
console . log ( `Test candidate link: ${ testInterview . candidate_link } ` );
# Create a test interview
data = {
'job' : {
'title' : 'Test Position' ,
'description' : 'This is a test interview' ,
'requirements' : 'No real requirements'
},
'candidate_email' : 'test@example.com' ,
'skills_to_assess' : [ 'JavaScript' , 'Problem Solving' ],
'test_mode' : True ,
'duration_minutes' : 30
}
response = requests.post(
'https://backend.jobhive.ai/api/v1/interviews/' ,
headers = headers,
json = data
)
test_interview = response.json()
print ( f "Test interview created: { test_interview[ 'session_id' ] } " )
print ( f "Test candidate link: { test_interview[ 'candidate_link' ] } " )
Mock Interview Results
Test interviews return mock results for development purposes:
{
"session_id" : "test_session_123" ,
"status" : "completed" ,
"overall_score" : 85.5 ,
"skill_scores" : {
"JavaScript" : 88.0 ,
"Problem Solving" : 83.0
},
"recommendations" : [
{
"type" : "hire" ,
"confidence" : 92.3 ,
"reasoning" : "Strong technical skills with excellent problem-solving approach"
}
],
"test_mode" : true
}
Rate Limits & Quotas
JobHive enforces the following rate limits based on your subscription:
Plan API Calls/min Concurrent Interviews Monthly Interviews Free 60 2 10 Starter 180 5 100 Professional 300 15 500 Enterprise 1000 50 Unlimited
All API responses include rate limit information:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1234567890
X-RateLimit-Resource: interviews
Handling Rate Limits
async function createInterviewWithRetry ( interviewData , maxRetries = 3 ) {
for ( let attempt = 1 ; attempt <= maxRetries ; attempt ++ ) {
try {
const response = await apiClient . post ( '/interviews/' , interviewData );
return response . data ;
} catch ( error ) {
if ( error . response ?. status === 429 && attempt < maxRetries ) {
const retryAfter = error . response . headers [ 'retry-after' ] || Math . pow ( 2 , attempt );
console . log ( `Rate limited, retrying after ${ retryAfter } seconds` );
await new Promise ( resolve => setTimeout ( resolve , retryAfter * 1000 ));
} else {
throw error ;
}
}
}
}
import time
import requests
def create_interview_with_retry ( interview_data , max_retries = 3 ):
for attempt in range ( 1 , max_retries + 1 ):
try :
response = requests.post(
'https://backend.jobhive.ai/api/v1/interviews/' ,
headers = headers,
json = interview_data
)
if response.status_code == 429 and attempt < max_retries:
retry_after = int (response.headers.get( 'retry-after' , 2 ** attempt))
print ( f "Rate limited, retrying after { retry_after } seconds" )
time.sleep(retry_after)
continue
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
if attempt == max_retries:
raise e
Troubleshooting
Authentication Error (401)
Common Causes:
Incorrect or missing API key in Authorization header
API key for wrong environment (dev vs prod)
Expired or revoked API key
Solutions: # Verify your API key format
curl -X GET "https://backend.jobhive.ai/api/v1/auth/verify/" \
-H "Authorization: Bearer YOUR_API_KEY"
# Check API key permissions
curl -X GET "https://backend.jobhive.ai/api/v1/auth/permissions/" \
-H "Authorization: Bearer YOUR_API_KEY"
Rate Limit Exceeded (429)
Symptoms:
HTTP 429 responses from API
“Rate limit exceeded” error messages
Delayed interview creation
Solutions:
Implement exponential backoff with jitter
Monitor rate limit headers in responses
Consider upgrading your subscription plan
Cache API responses to reduce redundant calls
Use webhooks instead of polling for status updates
Webhook Not Receiving Events
Troubleshooting Steps:
Verify webhook URL is publicly accessible (use tools like ngrok for local testing)
Check webhook secret is correctly configured
Ensure endpoint returns HTTP 200 status
Verify request signature validation
Check firewall and security group settings
Test Webhook: # Test webhook endpoint
curl -X POST "https://your-domain.com/webhooks/jobhive" \
-H "Content-Type: application/json" \
-H "X-JobHive-Signature: test-signature" \
-d '{"event": "test", "data": {}}'
WebSocket Connection Issues
Common Problems:
Connection drops during interviews
Unable to establish WebSocket connection
Authentication failures on WebSocket
Solutions: // Implement connection retry logic
const connectWithRetry = ( sessionId , apiKey , maxRetries = 3 ) => {
let retries = 0 ;
const connect = () => {
const socket = io ( `wss://backend.jobhive.ai/ws/interview/ ${ sessionId } /` , {
auth: { token: apiKey },
transports: [ 'websocket' , 'polling' ]
});
socket . on ( 'connect_error' , ( error ) => {
if ( retries < maxRetries ) {
retries ++ ;
setTimeout ( connect , Math . pow ( 2 , retries ) * 1000 );
}
});
return socket ;
};
return connect ();
};
Validation Errors:
Missing required fields (job title, candidate email)
Invalid skill names or difficulty levels
Malformed email addresses
Example Valid Request: {
"job" : {
"title" : "Software Engineer" ,
"description" : "Looking for a full-stack developer" ,
"requirements" : "React, Node.js, 3+ years experience"
},
"candidate_email" : "candidate@example.com" ,
"skills_to_assess" : [ "JavaScript" , "React" , "Node.js" ],
"duration_minutes" : 45 ,
"difficulty_level" : "intermediate"
}
Database Connection Problems: # Check PostgreSQL is running
docker ps | grep postgres
# Test database connection
psql postgresql://jobhive:password@localhost/jobhive_dev
Redis Connection Issues: # Check Redis is running
docker ps | grep redis
# Test Redis connection
redis-cli -h localhost -p 6379 ping
Django Migration Errors: # Reset migrations (development only)
python manage.py migrate --fake-initial
# Check migration status
python manage.py showmigrations
Support & Resources
Developer Support Get technical help from our engineering team
API Status Check real-time API status and incidents
Bug Reports Report bugs and request features via email
Email Support Contact our development team for technical support
Getting Help
When reaching out for support, please include:
API Version : Which API version you’re using
Request/Response : Full HTTP request and response (remove sensitive data)
Error Details : Complete error messages and stack traces
Environment : Development, staging, or production
Timestamp : When the issue occurred (with timezone)
Response Times:
Free Plan : 2-3 business days
Paid Plans : 24 hours for technical issues
Enterprise : Dedicated Slack channel with 4-hour response SLA