GetYourJob Eval API

openapi: 3.2.0
info:
  title: MatchingAgent Eval API
  description: 'AI-powered candidate-job matching API.


    ## Features


    - **Match candidates against offers** - Get scored matches with detailed analysis

    - **Explainable results** - Understand why a match is good or bad

    - **Flexible input** - Accept various data formats


    ## MVP Endpoints


    - `POST /v1/match` - Match a candidate against multiple offers

    - `GET /v1/health` - Health check


    ## Coming Soon


    - `POST /v1/enrich` - Enrich candidate profiles with external data

    - `POST /v1/parse-document` - Parse CV/resume documents'
  version: mvp-1.0.0
tags:
- name: Eval
paths:
  /v1/internal/eval/calibration:
    get:
      tags:
      - Eval
      summary: Inspect score calibrator state and distributions
      description: 'Returns metadata for the bundled isotonic calibrators (production `overall_score` + dev-only `quick_score`), an anchor-point curve so dashboards can render the mapping, and (optionally) a side-by-side raw vs calibrated histogram for the current eval label set. Default-OFF: when MA_ENABLE_CALIBRATION is unset, `overall_calibrator.enabled` reads false and the production scoring is unchanged. The quick calibrator is loadable regardless — it''s never applied in serving (would shift Layer-1 sort thresholds), only exposed here for distribution comparison.'
      operationId: get_calibration_state_v1_internal_eval_calibration_get
      parameters:
      - name: histogram
        in: query
        required: false
        schema:
          type: boolean
          description: When true, includes a side-by-side raw vs calibrated histogram computed on the eval label set.
          default: false
          title: Histogram
        description: When true, includes a side-by-side raw vs calibrated histogram computed on the eval label set.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Calibration State V1 Internal Eval Calibration Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/internal/eval/latest:
    get:
      tags:
      - Eval
      summary: Fetch the most recent eval reports
      description: Returns the most recent eval reports (written by ``scripts/evaluate.py``) as a JSON array, newest-first. Used by the GetYourJob admin eval dashboard. Use ``days`` for a time window (7/30/90) and ``limit`` as a hard cap.
      operationId: get_latest_eval_reports_v1_internal_eval_latest_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 0
          description: Max number of reports to return (0 returns []).
          default: 90
          title: Limit
        description: Max number of reports to return (0 returns []).
      - name: days
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 365
            minimum: 0
          - type: 'null'
          description: Optional time window in days. When set, returns reports whose embedded timestamp is within the last N days. Combine with ``limit`` for a safety cap.
          title: Days
        description: Optional time window in days. When set, returns reports whose embedded timestamp is within the last N days. Combine with ``limit`` for a safety cap.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
                title: Response Get Latest Eval Reports V1 Internal Eval Latest Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError