Feedback API

The Feedback API provides comprehensive interview performance analysis, including scoring, strengths, weaknesses, and CV optimization recommendations. Feedback is generated using AI analysis of the complete interview conversation.

Endpoints

Complete Interview & Generate Feedback

POST /session/<session_id>/complete

endpoint

Mark the interview as complete and generate AI-powered feedback.

Path Parameters

session_id

integer

required

The unique identifier of the interview session.

Response

Redirects to the feedback page after generating the analysis.

redirect

string

URL to the feedback page: /session/<session_id>/feedback

Example Request

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

Success Response

{
  "redirect": "/session/123/feedback",
  "feedback_id": 456
}

Error Responses

ValidationError

object

Returned when feedback generation is not possible.

error

string

Error message.

Example Errors:

“Feedback has already been generated for this session.”
“Cannot generate feedback for an empty interview.”
“Session not found”

AIServiceError

object

Returned when the AI service fails to generate feedback.

error

string

Error message from the AI service.

Get Feedback

GET /session/<session_id>/feedback

endpoint

Retrieve the generated feedback for a completed interview.

Path Parameters

session_id

integer

required

The unique identifier of the interview session.

Response

Returns an HTML page displaying comprehensive interview feedback.

feedback

object

The feedback analysis object.

integer

Unique feedback identifier.

session_id

integer

Associated session ID.

interview_score

integer

Performance score from 1-10.

strengths

string

Text describing the candidate’s strong points during the interview.

weaknesses

string

Text describing areas for improvement.

cv_improvements

string

Specific recommendations for optimizing the CV for the target role.

created_at

datetime

Timestamp when feedback was generated.

session

object

The associated session details.

integer

Session identifier.

job_title

string

Job title for this interview.

company_name

string

Company name.

Example Request

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

Example Response Data

{
  "feedback": {
    "id": 456,
    "session_id": 123,
    "interview_score": 8,
    "strengths": "Strong technical knowledge demonstrated in microservices architecture. Excellent communication skills with clear, structured answers. Good understanding of distributed systems concepts and practical experience with Docker and Kubernetes.",
    "weaknesses": "Could provide more specific metrics and quantifiable achievements. Some answers were too high-level and lacked concrete examples. Would benefit from more detailed explanations of problem-solving approaches.",
    "cv_improvements": "Add specific metrics to project descriptions (e.g., 'Improved system performance by 40%'). Include more details about leadership experience and team collaboration. Highlight cloud platform certifications if available. Add a technical skills section with proficiency levels for each technology.",
    "created_at": "2026-03-03T11:15:00Z"
  },
  "session": {
    "id": 123,
    "job_title": "Senior Software Engineer",
    "company_name": "TechCorp Inc"
  }
}

Error Responses

403 Forbidden: “You don’t have access to this session”
404 Not Found: “Feedback for session not found.” or session does not exist

Feedback Object Structure

The Feedback object contains comprehensive interview analysis:

integer

Unique identifier for the feedback record.

session_id

integer

Associated session ID (foreign key to sessions table).

interview_score

integer

Performance score ranging from 1 (poor) to 10 (excellent).

strengths

string

Detailed text analysis of what the candidate did well, including:

Strong technical answers
Good communication skills
Relevant experience demonstrated
Appropriate depth of knowledge

weaknesses

string

Constructive feedback on areas to improve, such as:

Missing details or examples
Areas of insufficient knowledge
Communication improvements
Response structure suggestions

cv_improvements

string

Specific, actionable recommendations for tailoring the CV to the target role:

Keywords to add
Sections to expand
Metrics to include
Format improvements
Skills to highlight

created_at

datetime

Timestamp when the feedback was generated (ISO 8601 format).

Feedback Generation Process

The feedback is generated through the following AI analysis process:

Input Data

Conversation History: Complete Q&A transcript from the interview
CV Text: Candidate’s uploaded resume
Job Description: Target job requirements
Job Title & Company: Interview context

AI Analysis

The AI analyzes:

Answer Quality: Depth, accuracy, and relevance of responses
Technical Skills: Demonstrated knowledge and experience
Communication: Clarity, structure, and articulation
CV Alignment: How well the CV matches responses and job requirements
Missing Elements: Gaps in answers or CV that could be addressed

Output Generation

The AI generates:

Interview Score (1-10): Holistic performance rating
Strengths: 3-5 key positive points
Weaknesses: 3-5 areas for improvement
CV Improvements: Specific, actionable suggestions tailored to the role

Interview Score Interpretation

9-10

Excellent

Outstanding performance. Strong technical skills, excellent communication, and well-aligned with the role. CV is comprehensive and relevant.

7-8

Good

Solid performance with minor areas for improvement. Good technical knowledge and communication. CV could be enhanced with more specific details.

5-6

Adequate

Acceptable performance but significant room for improvement. Some knowledge gaps or communication issues. CV needs substantial updates.

3-4

Needs Work

Below expectations. Notable knowledge gaps, unclear communication, or insufficient experience. CV requires major revisions.

1-2

Poor

Significant concerns. Major knowledge gaps, poor communication, or misaligned experience. Recommend additional preparation before applying.

Prerequisites

Feedback can only be generated when:

Interview is Complete: All 8 questions have been answered
Conversation Exists: At least one Q&A pair in the message history
No Existing Feedback: Feedback can only be generated once per session

Error Handling

HTTP Status Codes

302 Found: Successful redirect after feedback generation
400 Bad Request: Validation error (already exists, empty interview, etc.)
403 Forbidden: Unauthorized session access
404 Not Found: Session or feedback not found
500 Internal Server Error: AI service error or unexpected error

Common Errors

Already Generated

ValidationError

“Feedback has already been generated for this session.”Solution: Navigate to GET /session/<session_id>/feedback to view existing feedback.

Empty Interview

ValidationError

“Cannot generate feedback for an empty interview.”Solution: Complete the interview by answering questions before requesting feedback.

Session Not Found

NotFoundError

“Session not found”Solution: Verify the session ID is correct and exists.

AI Service Error

AIServiceError

“Failed to generate feedback: [AI provider error message]”Solution: The AI service may be temporarily unavailable. Try again in a few moments.

Example: Complete Workflow

# After answering 8 questions, complete the interview
curl -X POST https://your-domain.com/session/123/complete \
  -H "Cookie: session=your_session_cookie"

# Response: Redirects to /session/123/feedback

Integration with Other APIs

The Feedback API is the final step in the interview workflow:

Create Session (Sessions API)
Upload Documents (Documents API)
Conduct Interview (Interviews API)
Receive Feedback (Feedback API) ← You are here

Workflow Validation

Cannot access feedback without completing the interview
Interview must have reached the 8-question limit
Feedback is generated once and stored permanently
Attempting to regenerate feedback will return an error

AI Providers

Feedback generation supports multiple AI providers:

Google Gemini: Primary provider for feedback analysis
OpenRouter: Alternative provider with fallback support

The system includes retry logic with exponential backoff for reliability. If one provider fails, it automatically attempts the next available provider.

Example Feedback Output

{
  "id": 789,
  "session_id": 123,
  "interview_score": 7,
  "strengths": "\n- Demonstrated solid understanding of microservices architecture and containerization\n- Provided clear examples from previous projects\n- Good communication skills with structured responses\n- Showed problem-solving approach when discussing technical challenges\n",
  "weaknesses": "\n- Could provide more quantifiable metrics in answers (e.g., performance improvements, team size)\n- Some responses lacked specific technical implementation details\n- Missed opportunity to discuss testing and monitoring strategies\n- Would benefit from mentioning recent technologies and trends\n",
  "cv_improvements": "\n1. **Quantify Achievements**: Add specific metrics like 'Reduced deployment time by 60%' or 'Led team of 5 engineers'\n\n2. **Technical Skills Section**: Create a dedicated section with proficiency levels for Docker, Kubernetes, Python, etc.\n\n3. **Project Details**: Expand project descriptions to include scale, technologies used, and business impact\n\n4. **Leadership Experience**: Highlight any mentoring, code review, or technical decision-making responsibilities\n\n5. **Certifications**: If you have AWS, GCP, or Kubernetes certifications, prominently display them\n\n6. **Keywords for ATS**: Ensure job posting keywords appear in your CV (microservices, distributed systems, cloud-native, CI/CD)\n",
  "created_at": "2026-03-03T11:15:00Z"
}

Endpoints

AI Integration

Endpoints

Complete Interview & Generate Feedback

Path Parameters

Response

Example Request

Success Response

Error Responses

Get Feedback

Path Parameters

Response

Example Request

Example Response Data

Error Responses

Feedback Object Structure

Feedback Generation Process

Input Data

AI Analysis

Output Generation

Interview Score Interpretation

Prerequisites

Error Handling

HTTP Status Codes

Common Errors

Example: Complete Workflow

Integration with Other APIs

Workflow Validation

AI Providers

Example Feedback Output

Build docs developers (and LLMs) love

Endpoints

AI Integration

​Endpoints

​Complete Interview & Generate Feedback

​Path Parameters

​Response

​Example Request

​Success Response

​Error Responses

​Get Feedback

​Path Parameters

​Response

​Example Request

​Example Response Data

​Error Responses

​Feedback Object Structure

​Feedback Generation Process

​Input Data

​AI Analysis

​Output Generation

​Interview Score Interpretation

​Prerequisites

​Error Handling

​HTTP Status Codes

​Common Errors

​Example: Complete Workflow

​Integration with Other APIs

​Workflow Validation

​AI Providers

​Example Feedback Output

Build docs developers (and LLMs) love

Endpoints

Complete Interview & Generate Feedback

Path Parameters

Response

Example Request

Success Response

Error Responses

Get Feedback

Path Parameters

Response

Example Request

Example Response Data

Error Responses

Feedback Object Structure

Feedback Generation Process

Input Data

AI Analysis

Output Generation

Interview Score Interpretation

Prerequisites

Error Handling

HTTP Status Codes

Common Errors

Example: Complete Workflow

Integration with Other APIs

Workflow Validation

AI Providers

Example Feedback Output