Skip to main content
The Interviews API enables you to start, conduct, and track AI-powered mock interviews. Each interview consists of up to 8 adaptive questions tailored to the candidate’s CV and job description.

​
Endpoints

​
Get Interview Page

​
GET /session/<session_id>/interview
endpoint
Retrieve the interview interface for a specific session.

​
Path Parameters

​
session_id
integer
required
The unique identifier of the interview session.

​
Response

Returns an HTML page with the interview interface, including conversation history and progress.
​
session
object
The session details.
​
id
integer
Session identifier.
​
job_title
string
Job title for this interview.
​
company_name
string
Company name.
​
conversation
array
Array of message objects in chronological order.
​
id
integer
Message identifier.
​
session_id
integer
Associated session ID.
​
role
string
Message role: “assistant” (AI) or “user” (candidate).
​
content
string
Message content text.
​
timestamp
datetime
When the message was created.
​
progress
object
Interview progress information.
​
question_count
integer
Number of questions asked so far.
​
max_questions
integer
Maximum number of questions (8).
​
is_started
boolean
Whether the interview has started.
​
is_complete
boolean
Whether all questions have been answered.

​
Example Request

curl -X GET https://your-domain.com/session/123/interview \
  -H "Cookie: session=your_session_cookie"

​
Example Response Data

{
  "session": {
    "id": 123,
    "job_title": "Senior Software Engineer",
    "company_name": "TechCorp Inc"
  },
  "conversation": [
    {
      "id": 1,
      "session_id": 123,
      "role": "assistant",
      "content": "Tell me about your experience with distributed systems.",
      "timestamp": "2026-03-03T10:35:00Z"
    },
    {
      "id": 2,
      "session_id": 123,
      "role": "user",
      "content": "I have 3 years of experience building microservices...",
      "timestamp": "2026-03-03T10:36:15Z"
    }
  ],
  "progress": {
    "question_count": 2,
    "max_questions": 8,
    "is_started": true,
    "is_complete": false
  }
}

​
Error Responses

  • 403 Forbidden: “You don’t have access to this session”
  • 404 Not Found: Session does not exist
  • Redirect to Upload: If CV or job description is missing

​
Submit Answer

​
POST /session/<session_id>/message
endpoint
Submit an answer to the current interview question. Returns the next question via HTMX fragment.

​
Path Parameters

​
session_id
integer
required
The unique identifier of the interview session.

​
Request Parameters

​
answer
string
required
The candidate’s answer to the current question. Cannot be empty.

​
Response

Returns an HTML fragment containing the user’s message, AI’s next question (if any), and updated progress.
​
result
object
Result of submitting the answer.
​
next_question
string | null
The next question from the AI, or null if interview is complete.
​
is_complete
boolean
Whether the interview has reached the maximum number of questions.
​
question_count
integer
Updated count of questions asked.

​
Example Request

curl -X POST https://your-domain.com/session/123/message \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Cookie: session=your_session_cookie" \
  -d "answer=I have extensive experience with microservices architecture..."

​
Success Response (Interview Continues)

{
  "next_question": "Can you describe a challenging technical problem you solved recently?",
  "is_complete": false,
  "question_count": 3
}

​
Success Response (Interview Complete)

{
  "next_question": null,
  "is_complete": true,
  "question_count": 8
}

​
Error Responses

​
ValidationError
object
Returned when the answer is invalid.
​
error
string
Error message.
Example Errors:
  • “Answer cannot be empty.”
  • “Session not found”

​
Interview Flow

The interview follows this sequence:
  1. Start Interview: When the interview page is accessed for the first time, the AI generates the first question based on the CV and job description.
  2. Answer Submission: The candidate submits answers via POST to /session/<session_id>/message.
  3. Adaptive Questions: The AI generates follow-up questions based on:
    • Previous answers
    • CV content
    • Job description requirements
    • Number of questions remaining
  4. Completion: After 8 questions, the interview is marked complete and can proceed to feedback generation.

​
Interview Progress Object

The progress object tracks the interview state:
​
question_count
integer
Number of questions asked (0-8).
​
max_questions
integer
Maximum questions allowed (always 8).
​
is_started
boolean
True if at least one question has been asked.
​
is_complete
boolean
True when question_count reaches max_questions.

​
Message Object Structure

Each message in the conversation has the following structure:
​
id
integer
Unique message identifier.
​
session_id
integer
Associated session ID.
​
role
string
Message role: “assistant” (AI interviewer) or “user” (candidate).
​
content
string
The message text content.
​
timestamp
datetime
When the message was created (ISO 8601 format).

​
Prerequisites

Before starting an interview, the session must have:
  1. CV Text: Uploaded via the Documents API
  2. Job Description: Submitted via the Documents API
Attempting to access the interview page without these will redirect to the upload page with a warning message.

​
Error Handling

​
HTTP Status Codes

  • 200 OK: Successful request
  • 400 Bad Request: Validation error (empty answer, etc.)
  • 403 Forbidden: Unauthorized session access
  • 404 Not Found: Session not found
  • 500 Internal Server Error: AI service error or unexpected error

​
Error Fragment

When an error occurs during answer submission, an error HTML fragment is returned: 
{
  "error": true,
  "message": "Answer cannot be empty."
}

​
AI Interview Generation

The interview uses AI to:
  1. Generate First Question: Analyzes CV and job description to create a relevant opening question
  2. Generate Follow-up Questions: Uses conversation history to ask adaptive, contextual questions
  3. Maintain Context: Each question considers previous answers and remaining question count
The AI supports multiple providers (Gemini, OpenRouter) with automatic retry logic for reliability.

Build docs developers (and LLMs) love

Get started for freeTalk to us