Base URL (dev): http://localhost:8000. Swagger UI: /docs.
All requests/responses are JSON. Auth endpoints are public; everything else
requires Authorization: Bearer <JWT> (the frontend attaches this automatically
from the margito_token cookie via its proxy).
HTTP error convention: FastAPI {"detail": "..."}.
Create an account.
Errors: 409 email exists · 422 validation (password ≥8 chars, letters+digits).
// request
{ "email": "ada@example.com", "password": "Margito123" }
// 200 response — same shape as registerErrors: 401 invalid credentials.
Returns UserOut: { id, email, name, created_at }.
Returns ProfileOut. Errors: 404 no profile yet.
Full profile write. Request ProfileIn:
{
"name": "Ada",
"education_level": "Bachelors",
"field_of_study": "Computer Science",
"education_institution": "MIT", // optional
"graduation_year": 2025, // optional (1950–2100)
"skills": [{ "name": "Python", "proficiency": 4 }],
"interests": ["Web Development"],
"career_goal": "Become a backend developer",
"resume_text": "…", // optional
"pinned_role": "backend_dev", // optional
"career_stage": "working_professional", // optional: student | fresher | working_professional | career_switcher | returning
"years_of_experience": 3.5, // optional (0–60)
"current_job_title": "Junior Developer", // optional
"target_seniority": "Mid Level", // optional
"work_mode": ["Remote"], // optional list
"employment_type": ["Full-time"], // optional list
"availability": "Immediately", // optional
"projects": [{ "name": "…", "description": "…", "link": "https://…" }], // optional
"certifications": ["AWS Solutions Architect"], // optional
"languages": ["English"], // optional
"links": { "github": "https://…" } // optional
}Returns ProfileOut (adds id, normalized_skills, categories).
Same as PUT but 201 on first creation. Backwards-compatible with the earlier API.
ProfileOut:
{
"id": "…", "name": "Ada", "education_level": "…", "field_of_study": "…",
"education_institution": "…", "graduation_year": 2025,
"skills": [{ "name": "Python", "proficiency": 4 }], "interests": [],
"career_goal": "…", "resume_text": null, "pinned_role": "backend_dev",
"career_stage": "working_professional", "years_of_experience": 3.5,
"current_job_title": "…", "target_seniority": "…",
"work_mode": [], "employment_type": [], "availability": null,
"projects": [], "certifications": [], "languages": [], "links": {},
"normalized_skills": ["Python"], "categories": ["Web Development"]
}Returns RecommendationsOut computed from the user's stored profile:
{ "recommendations": [
{ "role_id": "backend_dev", "title": "Backend Developer", "fit_score": 78.4,
"missing_skills": ["Docker"], "matched_skills": ["Python", "SQL"],
"explanation": "Your Python and SQL background maps directly…" } ] }Explanations are LLM-enhanced when a Groq key is set, else rule-based. 404 if no profile.
Roadmap from the stored profile, with persisted completion and
percent_complete. 404 if no profile.
// request
{ "role_id": "backend_dev", "completed": ["skill:Python", "skill:SQL"] }Persists completion and returns the updated RoadmapOut. Completion is
tracked per skill (each subtask in a stage). completed may contain:
"skill:<name>"tokens — a single completed skill/subtask;- legacy whole-stage titles (e.g.
"Foundations") — expand to mark every skill in that stage complete (kept for backward compatibility).
percent_complete = completed skills / total skills across all stages × 100.
RoadmapOut:
{
"role_id": "backend_dev", "role_title": "Backend Developer",
"percent_complete": 15.4, "completed": ["skill:Python", "skill:SQL"],
"stages": [
{ "title": "Foundations", "description": "…", "skills": ["Python", "SQL"],
"resources": [{ "type": "course", "title": "…", "url": "https://…" }],
"estimated_hours": 40 } ] }// request
{ "resume_text": "…", "job_description": "… (optional)" }Runs the ATS scorer, upgrades suggestions via Groq when available, persists
the analysis to the user's profile. Returns ResumeOut:
{ "ats_score": 71.2,
"sub_scores": { "keyword_match": 60.0, "formatting_parseability": 90.0,
"section_completeness": 66.7, "action_verb_usage": 80.0,
"quantified_impact": 40.0 },
"suggestions": ["Add a dedicated Skills section…"],
"matched_keywords": ["python", "sql"], "parsed_sections": { "experience": "…" } }Returns the last stored ResumeOut. 404 if none.
Uploads a resume file — PDF, DOCX, TXT or Markdown (max 5 MB). The backend parses it to text, extracts structured data (skills, projects, education, links, certifications, languages), computes the ATS score over the whole document, and persists the result (text + analysis) to the user's profile — so the resume page and AI interview see it immediately.
POST /resume/upload
Content-Type: multipart/form-data
file: <binary>
job_description: Backend developer… (optional form field)Response — ResumeUploadOut (analysis is the same shape as ResumeOut):
{ "analysis": { "ats_score": 76.2, "sub_scores": { … }, "suggestions": […],
"matched_keywords": […], "parsed_sections": {…} },
"resume_text": "Aarav Sharma\nBackend Engineer…",
"structure": {
"summary": "Backend engineer with 5 years…",
"experience": ["Led a payments team of 4…"],
"education": ["- B.Tech in Computer Science, IIT Bombay, 2021"],
"education_fields": { "education_level": "Bachelor's degree",
"field_of_study": "Computer Science",
"education_institution": "IIT Bombay",
"graduation_year": "2021" },
"projects": [{ "name": "Resume Parser", "description": "…", "link": "https://github.com/…" }],
"skills": ["Python", "Django", "PostgreSQL"],
"certifications": [], "languages": ["English", "Hindi"],
"links": { "linkedin": "", "github": "https://github.com/…", "portfolio": "" } } }Errors: 400 for unsupported file types, files > 5 MB, or scanned/image PDFs
with no readable text (the UI then asks the user to paste instead).
5-stage recommendation pipeline:
- Feature extraction (31 features: skill, semantic, experience, preference, market, profile, structural)
- Learning-to-rank scoring with adaptive weights
- MMR diversity filtering (lambda=0.6)
- LLM re-ranking (top-20 via Groq, rule-based fallback)
- Output assembly with personalized explanations
Returns { "matches": [ { ...job, "match_score", "explanation", "matched_skills", "missing_skills", "strengths": [], "gaps": [], "learning_path": [] } ], "total": N }.
Currency note: source APIs report salaries in USD. Margito converts them to INR (₹) at
USD_TO_INR = 83.0(services/job_api_manager.py).salaryis a localized string (e.g."₹62,25,000 - ₹99,60,000/yr", Indian digit grouping) andmin_salary/max_salaryare numeric INR. Pay period (/yr,/mo,/hr) is preserved from the source string.
Requires full profile (onboarding completed). Query params: top_k (1-150, default 100).
// request
{ "query": "python developer", "location": "Remote", "page": 1, "top_k": 20 }Real-time JSearch API query with profile-based scoring.
Public job search via JSearch API. No auth required.
{ "job_id": "…", "title": "…", "company": "…", "url": "…", "match_score": 75.0, ... }Save a job to the user's saved list. Returns { "saved": true, "id": N }.
Unsave a job by URL.
Returns all saved jobs for the current user.
The interview is driven by a conversational AI agent (Groq LLM with a rule-based fallback). The agent:
- grounds questions in the candidate's saved profile (skills, interests,
career goal) and resume text (loaded server-side from
/profiles/me); - asks dynamic follow-ups on the candidate's actual answers, probes vague answers for specifics/measurable outcomes, and adapts difficulty;
- decides when the interview is over (up to a hard cap of
SOFT_MAX_QUESTIONS = 25as a safety limit, but typically ends much sooner based on candidate performance).
// request
{ "role_id": "backend_dev", "interview_type": "behavioral" } // behavioral | technical | mixed
// 201
{ "id": "…", "role_id": "backend_dev", "role_title": "Backend Developer",
"interview_type": "behavioral", "status": "in_progress", "question_index": 1,
"total_questions": 10, "current_question": "Tell me about yourself…",
"transcript": [{ "role": "interviewer", "content": "…", "at": "…" }],
"report": null, "started_at": "…", "completed_at": null }// request { "answer": "I led a team project…" }
// 200
{ "session_id": "…", "question_index": 2, "total_questions": 10, "done": false,
"next_question": "You mentioned the API layer — how did you test it?" }The agent reads the whole transcript (including the new answer) plus the
user's profile/resume when crafting next_question. When done: true, the
agent decided the interview was over (or the cap was reached); the session is
marked completed and the report can be generated.
Generates an in-depth report from the transcript and returns the session
with report:
{ "summary": "…", "overall_score": 74.0, "verdict": "Leaning hire",
"competencies": { "communication": 78.0, "technical_depth": 62.0, "structure": 80.0, "confidence": 76.0 },
"question_breakdown": [ { "question": "…", "evaluation": "…", "score": 70.0,
"strengths": "…", "improvements": "…" } ],
"strengths": ["…"], "gaps": ["…"], "suggestions": ["…"] }When no API key is configured the report falls back to rule-based heuristics (word counts, role-skill mentions, structure words, filler-word rate) that still produce the full shape above.
All of the user's sessions, newest first.
A single session (transcript + report). 404 if not owned by the user.
Real-time, full-duplex voice interview (Vapi-style). The browser connects
directly to the backend (ws://localhost:8000, not through the same-origin
HTTP proxy) and the auth cookie margito_token is sent on the WebSocket
handshake. Auth failure → { "type": "error", "message" } then close 1008.
Streaming pipeline (all free tiers):
- STT — the browser's Web Speech API sends final transcripts as JSON frames
(no audio upload, no key). A binary frame (WebM/WAV/MP3) is still accepted as
a fallback and transcribed server-side with Groq Whisper (
GROQ_STT_MODEL). - LLM — Groq streams token deltas; the server splits the reply into
sentences and emits each as a
partialevent as soon as it finishes. - TTS — edge-tts (free, no key) streams MP3 chunks per sentence, so audio starts while the model is still talking. No audio is embedded in JSON.
Protocol — client → server (JSON, or a binary audio frame):
{ "type": "user_text", "text": "I built a Django API…" } // new candidate answer
{ "type": "interrupt" } // barge-in: cancel in-flight turn
{ "type": "stop" } // graceful close
Protocol — server → client:
{ "type": "turn_start", "done": false, "greeting": true } // greeting = stored first question
…binary MP3 chunks… // streaming TTS audio
{ "type": "partial", "text": "<cumulative spoken so far>" } // lets the client ignore its own echo
{ "type": "turn_end", "done", "question_index": n, "total_questions": 10,
"transcript": […], "reply": "<full reply>" }
{ "type": "report", "transcript", "report", "role_title" } // interview over (session auto-completed)
{ "type": "error", "message" }
Interruption: on user_text/binary audio the server sets its interrupt flag,
cancels the in-flight LLM/TTS stream and immediately starts the next turn
(answer → follow-up). Missing GROQ_API_KEY → the same agent logic falls back
to the rule-based per-role question bank; the protocol is unchanged.
Returns aggregated metrics computed from the user's live profile, resume, roadmap, job matches, and interview sessions:
{ "profile_present": true,
"profile_completeness": 75.0, // % of key profile fields filled
"roadmap_progress": 28.6, // completed skills / total skills × 100
"resume_strength": 72.0, // ATS score from profile.resume_analysis
"match_strength": 85.3, // best job-match score (pgvector cosine)
"interview_readiness": 62.0, // average of roadmap + resume + match
"interview_count": 3, // number of completed interviews
"interview_avg_score": 71.4, // average overall_score across completed interviews
"interview_latest_score": 78.0, // most recent interview overall_score
"pinned_role": "fullstack_dev",
"total_roles": 56,
"categories": 11,
"skills": 267,
"aliases": 94 }When profile_present is false (no profile row), all numeric fields default to 0.0.
interview_readiness is a weighted composite: when interview sessions exist, it uses
0.5 × interview_avg + 0.2 × resume + 0.2 × match + 0.1 × roadmap; otherwise it
falls back to equal-weighted (resume + match + roadmap) / 3.
{ "status": "ok" }
{ "message": "Margito backend is running", "version": "1.0.0" }