Okia API Endpoints

All REST endpoints are under /api/v1.

Sessions

Create Session

POST /api/v1/sessions

Creates a new interview session. Called by YeboJobs backend.

Headers:

• X-API-Key: Service API key (required)
• X-Webhook-Secret: Secret for webhook auth (optional)

Request Body:

{
  "candidate_name": "John Doe",
  "candidate_phone": "+26878422613",
  "candidate_email": "john@example.com",
  "job_title": "Software Developer",
  "job_category": "technology",
  "job_description": "We're looking for...",
  "experience_level": "mid",
  "user_id": "cuid_user123",
  "application_id": "cuid_app456",
  "cv_url": "https://...",
  "cv_text": "Extracted CV text...",
  "max_questions": 10,
  "time_limit_minutes": 15,
  "webhook_url": "https://api.yebojobs.com/api/interviews/webhook/completed",
  "send_sms": true,
  "metadata": {
    "yebojobs_application_id": "app123",
    "yebojobs_job_id": "job456"
  }
}

Response:

{
  "id": "uuid-session-id",
  "session_token": "abc123xyz",
  "candidate_name": "John Doe",
  "status": "pending",
  "max_questions": 10,
  "time_limit_minutes": 15,
  "interview_url": "https://yebojobs.pages.dev/okia/abc123xyz",
  "created_at": "2024-01-15T10:00:00Z",
  "expires_at": "2024-01-16T10:00:00Z"
}

Get Session by Token

GET /api/v1/sessions/token/{token}

Used by frontend to load interview UI.

Response: Same as create session response.

Get Session by ID

GET /api/v1/sessions/{session_id}

Get Sessions by User

GET /api/v1/sessions/user/{user_id}?limit=10&offset=0

Response:

{
  "sessions": [...],
  "total": 5
}

Delete Session

DELETE /api/v1/sessions/{session_id}

Admin only. Returns 204 No Content.

---

Interview Flow

Start Interview

POST /api/v1/sessions/{session_id}/start

Starts the interview and returns greeting message.

Response:

{
  "session_id": "uuid",
  "status": "in_progress",
  "greeting": {
    "id": "message-uuid",
    "role": "okia",
    "message_type": "greeting",
    "content": "Hi John! Welcome to your interview for Software Developer...",
    "sequence_number": 1,
    "created_at": "2024-01-15T10:05:00Z"
  },
  "time_limit_minutes": 15
}

Pause Interview

POST /api/v1/sessions/{session_id}/pause

Pauses the interview timer.

Response:

{
  "status": "paused"
}

Resume Interview

POST /api/v1/sessions/{session_id}/resume

Resumes a paused interview.

Response:

{
  "status": "in_progress"
}

Complete Interview

POST /api/v1/sessions/{session_id}/complete

Manually completes the interview and generates report.

Response:

{
  "status": "completed",
  "closing_message": "Thank you for completing the interview...",
  "report": {
    "overall_score": 78,
    "grade": "B+",
    "recommendation": "consider",
    "recommendation_label": "Consider for Next Round",
    "categories": {
      "technical": 75,
      "communication": 82,
      "problem_solving": 80,
      "cultural_fit": 76
    },
    "executive_summary": "John demonstrated solid technical knowledge...",
    "strengths": ["Clear communication", "Problem-solving approach"],
    "improvements": ["Could elaborate more on technical details"]
  }
}

---

Messages

Send Message

POST /api/v1/sessions/{session_id}/messages

Submit candidate's answer.

Request Body:

{
  "content": "I would approach this problem by first..."
}

Response:

{
  "answer": {
    "id": "message-uuid",
    "role": "candidate",
    "content": "I would approach this problem by first...",
    "sequence_number": 4
  },
  "score": {
    "composite_score": 82,
    "summary": "Good problem-solving approach demonstrated."
  },
  "next_message": {
    "id": "message-uuid",
    "role": "okia",
    "content": "Great approach! Can you tell me about a time when...",
    "message_type": "question",
    "question_number": 3,
    "total_questions": 10,
    "category": "behavioral",
    "suggestions": [
      "A project at work",
      "A personal challenge",
      "Skip this question"
    ]
  }
}

Get Messages

GET /api/v1/sessions/{session_id}/messages?limit=50&before=2024-01-15T10:00:00Z

Response:

{
  "messages": [
    {
      "id": "uuid",
      "role": "okia",
      "message_type": "greeting",
      "content": "Hi John...",
      "sequence_number": 1,
      "created_at": "2024-01-15T10:05:00Z"
    },
    {
      "id": "uuid",
      "role": "okia",
      "message_type": "question",
      "content": "Tell me about your experience...",
      "question_number": 1,
      "question_category": "experience",
      "sequence_number": 2,
      "created_at": "2024-01-15T10:05:30Z"
    }
  ],
  "total": 12
}

---

Reports

Get Interview Report

GET /api/v1/sessions/{session_id}/report

Response:

{
  "session_id": "uuid",
  "candidate_name": "John Doe",
  "job_title": "Software Developer",
  "overall_score": 78,
  "grade": "B+",
  "recommendation": "consider",
  "recommendation_label": "Consider for Next Round",
  "scores": {
    "technical": 75,
    "communication": 82,
    "problem_solving": 80,
    "cultural_fit": 76
  },
  "executive_summary": "John demonstrated solid technical knowledge...",
  "strengths_analysis": [
    "Clear and articulate communication style",
    "Strong problem-solving methodology"
  ],
  "weaknesses_analysis": [
    "Could provide more technical depth",
    "Limited examples of leadership"
  ],
  "technical_assessment": "Shows proficiency in core technologies...",
  "behavioral_assessment": "Demonstrated adaptability...",
  "demonstrated_skills": ["JavaScript", "Problem-solving", "Communication"],
  "skill_gaps": ["System design", "Team leadership"],
  "interview_highlights": [
    {
      "question": "Describe a challenging project",
      "highlight": "Excellent example of debugging approach"
    }
  ],
  "red_flags": [],
  "follow_up_questions": [
    "How would you handle larger scale systems?",
    "Describe your experience mentoring others"
  ],
  "duration_minutes": 14,
  "questions_answered": 10,
  "created_at": "2024-01-15T10:20:00Z"
}

Generate PDF Report

GET /api/v1/sessions/{session_id}/report/pdf

Returns PDF download of the interview report.

---

Onboarding (Service Workers)

Start Onboarding Chat

POST /api/v1/onboarding/start

Starts AI chat for service worker profile creation.

Request Body:

{
  "user_id": "cuid_user123",
  "session_type": "worker_onboarding"
}

Response:

{
  "session_id": "uuid",
  "session_token": "token",
  "greeting": "Hi! I'm here to help you set up your service profile..."
}

Send Onboarding Message

POST /api/v1/onboarding/{session_id}/message

Request Body:

{
  "content": "I'm a plumber with 10 years experience"
}

Response:

{
  "response": "Great! 10 years is impressive. What areas do you cover?",
  "extracted_data": {
    "skills": ["plumbing"],
    "years_experience": 10
  },
  "profile_complete": false
}

---

Health

Health Check

GET /health

Response:

{
  "status": "healthy",
  "service": "okia-service",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:00:00Z"
}

API Health

GET /api/v1/health

Includes database connectivity check.

---

WebSocket Events

Connect to: wss://okia-service.../socket.io

Client → Server Events

Event	Payload	Description
join_session	{ session_token: string }	Join interview room
send_message	{ content: string }	Send answer
typing	{ is_typing: boolean }	Typing indicator
pause	{}	Pause interview
resume	{}	Resume interview
complete	{}	Complete interview

Server → Client Events

Event	Payload	Description
session_joined	{ session: SessionData }	Joined successfully
message	{ message: MessageData }	New message (question/response)
score	{ score: ScoreData }	Answer scored
status_update	{ status: string }	Session status changed
interview_complete	{ report: ReportSummary }	Interview finished
error	{ message: string }	Error occurred
typing	{ is_typing: boolean }	Okia typing indicator