Skip to main content
POST
/
api
/
interview
Create Interview Report
curl --request POST \
  --url https://api.example.com/api/interview/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "jobDescription": "<string>",
  "title": "<string>",
  "jobTitle": "<string>",
  "selfDescription": "<string>"
}
'
{
  "message": "<string>",
  "interviewReport": {
    "_id": "<string>",
    "user": "<string>",
    "title": "<string>",
    "jobDescription": "<string>",
    "resume": "<string>",
    "selfDescription": "<string>",
    "matchScore": 123,
    "technicalQuestions": [
      {
        "question": "<string>",
        "intention": "<string>",
        "answer": "<string>"
      }
    ],
    "behavioralQuestions": [
      {
        "question": "<string>",
        "intention": "<string>",
        "answer": "<string>"
      }
    ],
    "skillGaps": [
      {
        "skill": "<string>",
        "severity": "<string>"
      }
    ],
    "preparationPlan": [
      {
        "day": 123,
        "focus": "<string>",
        "tasks": [
          {}
        ]
      }
    ],
    "createdAt": "<string>",
    "updatedAt": "<string>"
  }
}
Generate a new interview report based on user self description, resume file (PDF/DOCX), and job description.

​
Authentication

This endpoint requires authentication. The JWT token must be sent as an HTTP-only cookie named token. This is automatically handled by the browser after successful login.

​
Request Body

This endpoint accepts multipart/form-data with the following fields:
​
jobDescription
string
required
The job description for the position the candidate is applying to. This field is required and cannot be empty.
​
title
string
The title of the job position. If not provided, the system will derive a title from the job description or use “Untitled Position” as fallback.
​
jobTitle
string
Alternative field name for job title. Used as fallback if title is not provided.
​
selfDescription
string
A self-description or summary provided by the candidate. Either this field or the resume file must be provided.
​
resume
file
Resume file upload. Accepts PDF or DOCX format. Either this field or selfDescription must be provided.Supported formats:
  • PDF (.pdf) - Detected via magic bytes: %PDF (0x25 0x50 0x44 0x46)
  • DOCX (.docx) - Detected via magic bytes: PK.. (0x50 0x4b 0x03 0x04)
File detection: The system uses magic bytes detection for reliable file type identification, falling back to MIME type and file extension if needed.Text extraction:
  • PDF files are parsed using pdf-parse
  • DOCX files are parsed using mammoth
  • If parsing fails (e.g., scanned PDFs), the file is sent directly to the AI service for processing

​
Example Request

curl -X POST https://api.example.com/api/interview/ \
  -b "token=YOUR_JWT_TOKEN" \
  -F "jobDescription=We are looking for a Senior Software Engineer with 5+ years of experience in React and Node.js..." \
  -F "title=Senior Software Engineer" \
  -F "selfDescription=I am a full-stack developer with 6 years of experience..." \
  -F "resume=@/path/to/resume.pdf"

const formData = new FormData();
formData.append('jobDescription', 'We are looking for a Senior Software Engineer...');
formData.append('title', 'Senior Software Engineer');
formData.append('selfDescription', 'I am a full-stack developer...');
formData.append('resume', fileInput.files[0]);

fetch('https://api.example.com/api/interview/', {
  method: 'POST',
  credentials: 'include', // Important: Include cookies
  body: formData
});

​
Response

​
message
string
Success message indicating the interview report was generated successfully.
​
interviewReport
object
The generated interview report object.

​
Success Response (201 Created)

{
  "message": "Interview report generated successfully.",
  "interviewReport": {
    "_id": "507f1f77bcf86cd799439011",
    "user": "507f191e810c19729de860ea",
    "title": "Senior Software Engineer",
    "jobDescription": "We are looking for a Senior Software Engineer...",
    "resume": "John Doe\nSoftware Engineer\n...",
    "selfDescription": "I am a full-stack developer...",
    "matchScore": 85,
    "technicalQuestions": [
      {
        "question": "Can you explain the virtual DOM in React and how it improves performance?",
        "intention": "To assess understanding of React's core concepts and performance optimization",
        "answer": "The virtual DOM is a lightweight copy of the actual DOM. React uses it to minimize direct DOM manipulations by..."
      }
    ],
    "behavioralQuestions": [
      {
        "question": "Tell me about a time when you had to work with a difficult team member.",
        "intention": "To evaluate interpersonal skills and conflict resolution abilities",
        "answer": "Use the STAR method: Situation, Task, Action, Result. Focus on how you..."
      }
    ],
    "skillGaps": [
      {
        "skill": "Kubernetes",
        "severity": "medium"
      },
      {
        "skill": "GraphQL",
        "severity": "low"
      }
    ],
    "preparationPlan": [
      {
        "day": 1,
        "focus": "React fundamentals and advanced concepts",
        "tasks": [
          "Review React hooks and their use cases",
          "Practice implementing custom hooks",
          "Study React performance optimization techniques"
        ]
      },
      {
        "day": 2,
        "focus": "Node.js and backend architecture",
        "tasks": [
          "Review REST API design principles",
          "Study microservices architecture patterns",
          "Practice writing Express middleware"
        ]
      }
    ],
    "createdAt": "2026-03-03T10:30:00.000Z",
    "updatedAt": "2026-03-03T10:30:00.000Z"
  }
}

​
Error Responses

​
400 Bad Request - Missing Job Description

{
  "message": "Job description is required (send as 'jobDescription')."
}

​
400 Bad Request - Missing Resume and Self Description

{
  "message": "Either a resume file (field 'resume') or 'selfDescription' is required."
}

​
400 Bad Request - Unsupported File Type

{
  "message": "Unsupported resume file type. Please upload a PDF or DOCX."
}

​
400 Bad Request - Unable to Read Resume

{
  "message": "Unable to read the uploaded resume. Please upload a valid PDF/DOCX or provide 'selfDescription'."
}

​
400 Bad Request - Empty Resume Content

{
  "message": "Could not extract text from the resume file. Please upload a text-based PDF/DOCX or provide 'selfDescription'."
}

​
400 Bad Request - Validation Error

{
  "message": "Validation error message from MongoDB schema"
}

​
401 Unauthorized

Returned when the authentication token is missing or invalid.

​
502 Bad Gateway - AI Service Error

{
  "message": "AI service failed to generate interview report. Please try again."
}

​
Notes

  • The AI service uses Google’s Gemini 3 Flash Preview model to generate comprehensive interview reports
  • Resume text extraction supports both structured (text-based) and unstructured (scanned) documents
  • If local parsing fails, the system automatically falls back to sending the raw file to the AI service
  • The Zod schema defined in ai.service.js ensures structured and validated output from the AI model
  • Magic bytes detection provides robust file type identification, particularly useful for files uploaded from Windows systems where MIME types may be unreliable

Build docs developers (and LLMs) love

Get started for freeTalk to us