Liya Engine

Conduct a multi-turn AI-powered mock interview with real-time feedback on answers.

POST /v1/hiring/mock-interview

Runs a conversational mock interview session. Each call processes the candidate's latest answer and returns the next question, along with feedback on the response provided. Requires session_id to maintain continuity across turns.

Required inputs

Field	Type	Notes
`input.user_id`	`string`	Your platform's user ID
`input.profile`	`ProfileInput`	Candidate profile for personalised questions
`input.message`	`string`	Candidate's answer to the current question

Optional inputs

Field	Type	Notes
`input.resume`	`ResumeInput`	Resume context for experience-based questions
`input.job_description`	`JobDescriptionInput`	Tailors questions to a specific role
`input.interview_context`	`InterviewContextInput`	Interview type, round, focus areas
`input.session_history`	`SessionHistoryInput`	Prior turns (auto-managed via `session_id`)
`session_id`	`string`	Continue an existing interview session

InterviewContextInput

{
  "interview_type": "behavioral",    // "behavioral" | "technical" | "case_study" | "system_design" | "culture_fit"
  "interview_round": "first_round",  // "phone_screen" | "first_round" | "second_round" | "final_round"
  "focus_areas": ["leadership", "conflict resolution"],
  "time_limit_minutes": 45,
  "company_research": "Stripe is a payments infrastructure company..."
}

Session flow

Turn 1: session_id omitted → engine creates session, returns opening question
Turn 2+: session_id from previous response → engine continues interview
Final turn: engine detects completion and returns summary feedback

Example — turn 1

curl -X POST https://api.liyaengine.ai/v1/hiring/mock-interview \
  -H "x-api-key: $LIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "user_id": "usr_123",
      "profile": { "title": "Senior Engineer", "years_of_experience": 8 },
      "interview_context": {
        "interview_type": "behavioral",
        "interview_round": "first_round"
      }
    }
  }'

Response (turn 1):

{
  "success": true,
  "data": {
    "output": {
      "message": "Tell me about a time you had to navigate a significant technical disagreement with a colleague. How did you handle it?",
      "turn": 1,
      "feedback_on_previous": null
    },
    "session_id": "ses_interview_abc"
  }
}

Example — turn 2

-d '{
  "input": {
    "user_id": "usr_123",
    "message": "At Acme Corp, my colleague and I disagreed on whether to use a message queue or direct HTTP calls for our notification service..."
  },
  "session_id": "ses_interview_abc"
}'

Response (turn 2):

{
  "data": {
    "output": {
      "message": "That's a solid example. Follow-up: what was the outcome, and in hindsight would you have approached the disagreement differently?",
      "turn": 2,
      "feedback_on_previous": {
        "strengths": ["Clear problem framing", "Described your decision-making process"],
        "improvements": ["Quantify the outcome — what did the final choice achieve?"],
        "score": 72
      }
    },
    "session_id": "ses_interview_abc"
  }
}

Mock Interview