openapi: 3.2.0
info:
  title: Resume Agent Match API
  description: Query a candidate's professional profile. Use queryProfile for natural language questions, matchJob to score against a job description, and the GET endpoints for structured profile data.
  version: 1.0.0
servers:
- url: https://agent.yuens.me
tags:
- name: Match
paths:
  /match:
    post:
      operationId: matchJob
      summary: Score the candidate against a job description
      description: Paste a job description to get a structured fit score. Returns a 0–1 fit score, matched skills, gaps, and a hiring recommendation. Use this when the user shares a role they're considering.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - job_description
              properties:
                job_description:
                  type: string
                  description: The full job description text
      responses:
        '200':
          description: Fit score and breakdown
          content:
            application/json:
              schema:
                type: object
                properties:
                  fit_score:
                    type: number
                    minimum: 0
                    maximum: 1
                    description: Overall fit score, 0–1 — a weighted average over the qualities this specific JD raised, not a fixed skills/experience/domain split
                  matched:
                    type: array
                    items:
                      type: string
                    description: Skills and experience that match
                  gaps:
                    type: array
                    items:
                      type: string
                    description: Missing or weak areas
                  verdict:
                    type: string
                  recommended_action:
                    type: string
                    enum:
                    - apply
                    - apply-with-tailoring
                    - pass
                  scoring:
                    type: object
                    description: Per-quality detail. Each JD is extracted into the specific qualities it raises (not a fixed checklist), then each is scored independently.
                    properties:
                      required_qualities:
                        type: array
                        description: Qualities extracted from the JD text itself
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            category:
                              type: string
                              enum:
                              - skill
                              - experience
                              - domain
                            jd_importance:
                              type: string
                              enum:
                              - must_have
                              - preferred
                      scored_qualities:
                        type: array
                        description: Each required quality scored against the candidate profile
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            category:
                              type: string
                              enum:
                              - skill
                              - experience
                              - domain
                            jd_importance:
                              type: string
                              enum:
                              - must_have
                              - preferred
                            verdict:
                              type: string
                              enum:
                              - matched
                              - partial
                              - missing
                            evidence_grade:
                              type: string
                              enum:
                              - verified
                              - claimed
                              - absent
                              description: verified = backed by a dated project or employment record; claimed = prose only; absent = no support found
      tags:
      - Match