Skip to content

Latest commit

 

History

History
367 lines (308 loc) · 14.9 KB

API.md

File metadata and controls

367 lines (308 loc) · 14.9 KB

Margito — API Reference

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": "..."}.


Auth

POST /auth/register — public

Create an account.

// request
{ "name": "Ada", "email": "ada@example.com", "password": "Margito123" }
// 201 response
{ "access_token": "<jwt>", "token_type": "bearer", "user": { "id": "…", "email": "ada@example.com", "name": "Ada", "created_at": "…" } }

Errors: 409 email exists · 422 validation (password ≥8 chars, letters+digits).

POST /auth/login — public

// request
{ "email": "ada@example.com", "password": "Margito123" }
// 200 response — same shape as register

Errors: 401 invalid credentials.

GET /auth/me — auth

Returns UserOut: { id, email, name, created_at }.


Profile

GET /profiles/me — auth

Returns ProfileOut. Errors: 404 no profile yet.

PUT /profiles/me — auth (upsert)

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).

POST /profiles/ — auth

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"]
}

Recommendations

GET /recommendations/me — auth

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

GET /roadmap/me?role_id= — auth

Roadmap from the stored profile, with persisted completion and percent_complete. 404 if no profile.

PUT /roadmap/me/progress?role_id= — auth

// 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 } ] }

Resume

POST /resume/analyze — auth

// 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": "…" } }

GET /resume/me — auth

Returns the last stored ResumeOut. 404 if none.

POST /resume/upload — auth (multipart/form-data)

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).


Jobs

GET /jobs/auto-fetch?top_k=100 — auth

5-stage recommendation pipeline:

  1. Feature extraction (31 features: skill, semantic, experience, preference, market, profile, structural)
  2. Learning-to-rank scoring with adaptive weights
  3. MMR diversity filtering (lambda=0.6)
  4. LLM re-ranking (top-20 via Groq, rule-based fallback)
  5. 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). salary is a localized string (e.g. "₹62,25,000 - ₹99,60,000/yr", Indian digit grouping) and min_salary/max_salary are 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).

POST /jobs/live-search — auth

// request
{ "query": "python developer", "location": "Remote", "page": 1, "top_k": 20 }

Real-time JSearch API query with profile-based scoring.

GET /jobs/search?q=python&location=&page=1

Public job search via JSearch API. No auth required.

POST /jobs/save — auth

{ "job_id": "…", "title": "…", "company": "…", "url": "…", "match_score": 75.0, ... }

Save a job to the user's saved list. Returns { "saved": true, "id": N }.

DELETE /jobs/save?url=... — auth

Unsave a job by URL.

GET /jobs/saved — auth

Returns all saved jobs for the current user.


Interview

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 = 25 as a safety limit, but typically ends much sooner based on candidate performance).

POST /interview/sessions — auth

// 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 }

POST /interview/sessions/{id}/answer — auth

// 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.

POST /interview/sessions/{id}/complete — auth

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.

GET /interview/sessions — auth

All of the user's sessions, newest first.

GET /interview/sessions/{id} — auth

A single session (transcript + report). 404 if not owned by the user.

WS /interview/sessions/{id}/ws — auth (cookie)

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 partial event 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.


Dashboard

GET /dashboard/me — auth

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.


Health

GET /health — public

{ "status": "ok" }

GET / — public

{ "message": "Margito backend is running", "version": "1.0.0" }