openapi: 3.2.0
info:
  contact:
    email: support@aiapplyd.com
    name: AI Applyd
    url: https://aiapplyd.com
  description: 'The AI Applyd API runs the whole job hunt for you: it matches you to roles that fit your profile, rewrites your resume for each posting, writes the cover letter the form asks for, and auto-applies across the major applicant tracking systems.'
  license:
    name: Proprietary
    url: https://aiapplyd.com/legal/terms
  title: AI Applyd Analytics API
  version: 115c47ce
servers:
- description: Current environment
  url: https://api.aiapplyd.com/api/v1
security:
- BearerAuth: []
tags:
- name: Analytics
paths:
  /analytics:
    get:
      tags:
      - Analytics
      summary: Get Application Analytics
      description: Get analytics dashboard data for job applications.
      responses:
        '200':
          description: Analytics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: getAnalytics
  /analytics/patterns:
    get:
      description: 'Strategic insights derived deterministically from the user''s applications: conversion funnel by archetype / remote-policy / score band, top blockers, tech-stack gaps, data-driven score floor, and prioritized recommendations. Returns `{status: "insufficient_data"}` when fewer than 5 applications have moved past Evaluated.'
      summary: Get Strategic Application Insights
      tags:
      - Analytics
      responses:
        '200':
          description: Pattern analysis (ready) or insufficient_data sentinel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatternAnalysisResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: getAnalyticsPatterns
  /analytics/recommendations/apply:
    post:
      description: 'Apply a structured pattern-analyzer recommendation. The actionType + actionPayload are produced by the analyzer and round-tripped through the FE. Idempotent: repeat-applies do not double-write.'
      summary: Apply Pattern-Analyzer Recommendation
      tags:
      - Analytics
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyRecommendationRequest'
      responses:
        '200':
          description: Recommendation applied (or idempotent no-op).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplyRecommendationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: postAnalyticsRecommendationsApply
components:
  schemas:
    Recommendation:
      type: object
      properties:
        action:
          type: string
          description: One concrete action the user can take next. Phrased as an imperative.
          example: Filter out roles with match score below 4.0 - none have progressed.
        actionPayload:
          type: object
          additionalProperties: {}
          description: Per-action JSON payload. Empty / omitted for noop actions or legacy text-only recs.
          example:
            threshold: 4
        actionType:
          type: string
          enum:
          - raise_score_floor
          - filter_remote_policy
          - deprioritize_archetype
          - noop
          description: Structured action enum. Absent / `noop` means the recommendation is informational only (no Apply button).
          example: raise_score_floor
        appliedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When this recommendation's target state was already in effect at analysis time. Null / absent = still actionable.
          example: '2026-05-10T12:34:56.000Z'
        impact:
          type: string
          enum:
          - high
          - medium
          - low
          description: Coarse expected-impact bucket for a recommendation. Computed from sample size + outcome shift, not author-supplied.
          example: high
        reasoning:
          type: string
          description: 'Why this recommendation: which signal in the data triggered it (counts, share, conversion deltas).'
          example: 12 of 12 applications below 4.0 ended in no_response or rejection.
        template:
          $ref: '#/components/schemas/RecommendationTemplate'
      required:
      - action
      - impact
      - reasoning
      - template
      additionalProperties: false
    PatternAnalysisData:
      type: object
      properties:
        blockers:
          type: array
          items:
            $ref: '#/components/schemas/BlockerRow'
          description: Top blockers ordered by count desc.
        funnel:
          type: object
          properties:
            byArchetype:
              type: array
              items:
                $ref: '#/components/schemas/ArchetypeFunnelRow'
            byRemotePolicy:
              type: array
              items:
                $ref: '#/components/schemas/RemotePolicyFunnelRow'
            byScoreBucket:
              type: array
              items:
                $ref: '#/components/schemas/ScoreBucketFunnelRow'
          required:
          - byArchetype
          - byRemotePolicy
          - byScoreBucket
          additionalProperties: false
        recommendations:
          type: array
          items:
            $ref: '#/components/schemas/Recommendation'
          description: Recommendations ordered by impact (high → low) and tie-broken by sample size.
        scoreFloor:
          type:
          - number
          - 'null'
          example: 4.2
        skillGaps:
          type: array
          items:
            $ref: '#/components/schemas/SkillGapRow'
          description: Skill slugs over-represented in negative outcomes.
        totalApplications:
          type: integer
      required:
      - blockers
      - funnel
      - recommendations
      - scoreFloor
      - skillGaps
      - totalApplications
      additionalProperties: false
    AnalyticsResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AnalyticsData'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    ScoreBucketFunnelRow:
      type: object
      properties:
        bucket:
          type: string
          enum:
          - lt_3
          - 3_to_4
          - 4_to_4_5
          - gte_4_5
          description: Match-score band for funnel breakdowns. Stored as a stable slug so the FE label can change without breaking the API contract.
          example: gte_4_5
        conversionRate:
          type: number
        progressed:
          type: integer
        total:
          type: integer
      required:
      - bucket
      - conversionRate
      - progressed
      - total
      additionalProperties: false
    DailyApplication:
      type: object
      properties:
        count:
          type: integer
        date:
          type: string
          description: Date in YYYY-MM-DD format
          example: '2026-03-24'
      required:
      - count
      - date
      additionalProperties: false
    MatchQualityWeek:
      type: object
      properties:
        excellent:
          type: integer
          description: Roles scored 90 or above
        fair:
          type: integer
          description: Roles scored 60 to 79
        strong:
          type: integer
          description: Roles scored 80 to 89
        week:
          type: string
          description: ISO year-week key, e.g. 2026-31
          example: 2026-31
      required:
      - excellent
      - fair
      - strong
      - week
      additionalProperties: false
    PatternAnalysisResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PatternAnalysisResult'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    ArchetypeFunnelRow:
      type: object
      properties:
        archetype:
          type: string
          enum:
          - software_engineer_frontend
          - software_engineer_backend
          - software_engineer_fullstack
          - software_engineer_mobile
          - software_engineer_embedded
          - software_engineer_games
          - software_engineer_generic
          - devops_sre
          - platform_infra
          - security_engineer
          - qa_test
          - data_engineer
          - data_scientist
          - data_analyst
          - ml_engineer
          - ai_research
          - product_manager
          - project_program_manager
          - designer_product
          - designer_ux_research
          - designer_visual
          - engineering_manager
          - technical_writer
          - developer_advocate
          - solutions_engineer
          - support_engineer
          - sales
          - marketing
          - operations
          - executive
          - finance
          - legal
          - hr_recruiting
          - customer_success
          - healthcare
          - creative-design
          - trades-manual
          - education
          - hospitality
          - logistics-supply
          - manufacturing
          - gov-nonprofit
          - marketing-sales
          - consulting
          - retail
          - insurance
          - admin_office
          - other
          - robotics_engineer
          - control_systems_engineer
          - mechatronics_engineer
          - firmware_engineer
          - fpga_engineer
          - hardware_engineer
          - electrical_engineer
          - rf_engineer
          - analog_engineer
          - biomedical_engineer
          - aerospace_engineer
          - avionics_engineer
          - simulation_engineer
          - computer_vision_engineer
          - autonomous_vehicles_engineer
          - graphics_engineer
          - blockchain_engineer
          - smart_contract_engineer
          - game_designer
          - ios_engineer
          - android_engineer
          - mlops_engineer
          - ai_infrastructure_engineer
          - llm_engineer
          - prompt_engineer
          - research_engineer
          - applied_scientist
          - cloud_architect
          - solutions_architect
          - enterprise_architect
          - release_engineer
          - network_engineer
          - systems_engineer
          - database_administrator
          - appsec_engineer
          - pentest_engineer
          - soc_analyst
          - incident_responder
          - analytics_engineer
          - data_architect
          - bioinformatics_engineer
          - computational_biologist
          - quant_analyst
          - quant_developer
          - trading_systems_engineer
          - risk_analyst
          - sdet
          - automation_engineer
          - product_manager_growth
          - ux_writer
          - content_designer
          - design_engineer
          - documentation_engineer
          - customer_engineer
          - implementation_engineer
          - civil_engineer
          - mechanical_engineer
          description: Canonical role family for matching
          example: software_engineer_frontend
        conversionRate:
          type: number
          description: progressed / total expressed as a 0..1 ratio. Rounded to 3 decimals.
          example: 0.214
        progressed:
          type: integer
        total:
          type: integer
      required:
      - archetype
      - conversionRate
      - progressed
      - total
      additionalProperties: false
    OutcomeMetrics:
      type: object
      properties:
        emailResponseRate:
          type: number
          description: Share of classified inbound job emails that carry a positive signal (interview / scheduling / offer), as a percentage. 0 when no emails are classified.
          example: 42.5
        interviewsBooked:
          type: integer
          description: Applications that reached an interview-booked outcome (stage phone_screen/interview, or interview_booked_at set).
          example: 3
        nextInterviewResultId:
          type:
          - integer
          - 'null'
          description: Application-result id behind the SOONEST upcoming interview event, for the applications deep-link. Null when that event has no application behind it; absent on payloads that do not resolve it.
          example: 1481
        offers:
          type: integer
          description: Applications with an offer outcome (applicationStage = offered).
          example: 1
        positiveEmailSignals:
          type: integer
          description: Count of inbound emails classified as a positive signal (interview_invite / scheduling / reschedule / offer_letter).
          example: 5
        upcomingInterviews:
          type: integer
          description: Synced calendar events flagged as interviews whose start time is in the future.
          example: 2
      required:
      - emailResponseRate
      - interviewsBooked
      - offers
      - positiveEmailSignals
      - upcomingInterviews
      additionalProperties: false
      description: Real-outcome success metrics from the email + calendar pipeline (interviews booked, offers, upcoming interviews, email response rate).
    PatternAnalysisReady:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PatternAnalysisData'
        status:
          type: string
          enum:
          - ready
      required:
      - data
      - status
      additionalProperties: false
    ApplyRecommendationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ApplyRecommendationResult'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    PatternAnalysisInsufficient:
      type: object
      properties:
        current:
          type: integer
          description: Number of applications the user currently has past Evaluated.
        status:
          type: string
          enum:
          - insufficient_data
        threshold:
          type: number
          enum:
          - 5
      required:
      - current
      - status
      - threshold
      additionalProperties: false
    AnalyticsData:
      type:
      - object
      - 'null'
      properties:
        atsScoreDistribution:
          type: object
          properties:
            excellent:
              type: integer
              description: Scores >= 80
            fair:
              type: integer
              description: Scores >= 40 and < 60
            good:
              type: integer
              description: Scores >= 60 and < 80
            poor:
              type: integer
              description: Scores < 40
          required:
          - excellent
          - fair
          - good
          - poor
          additionalProperties: false
          description: ATS score distribution across 4 buckets
        avgAtsScore:
          type:
          - number
          - 'null'
          description: Average ATS score across all scored jobs
        dailyAnswers:
          type: array
          items:
            $ref: '#/components/schemas/DailyApplication'
          description: Employer-confirmed answers per day for the last 14 days
        dailyApplications:
          type: array
          items:
            $ref: '#/components/schemas/DailyApplication'
          description: Application counts per day for the last 14 days
        matchQualityByWeek:
          type: array
          items:
            $ref: '#/components/schemas/MatchQualityWeek'
          description: Roles scored for this user per ISO week over the last 8 weeks, split into quality bands. Weeks with no supply are omitted.
        monthlyApplications:
          type: integer
          description: Jobs applied this month
        outcomes:
          allOf:
          - $ref: '#/components/schemas/OutcomeMetrics'
          - description: Real-outcome success metrics from the email + calendar pipeline.
        previousWeekApplications:
          type: integer
          description: Jobs applied 14-7 days ago for trend comparison
        recentActivity:
          type: array
          items:
            type: object
            properties:
              company:
                type:
                - string
                - 'null'
              companyDomain:
                type:
                - string
                - 'null'
                description: Trusted company-intel domain (company.domain) for the FE logo favicon fallback
              companyLogoUrl:
                type:
                - string
                - 'null'
                description: Company logo URL (company-intel R2 logo, falling back to the scraped snapshot)
              id:
                type: integer
              status:
                type: string
                enum:
                - saved
                - preparing
                - applied
                - interviewing
                - offered
                - rejected
                - archived
                description: Status of a job listing
                example: saved
              title:
                type: string
              updatedAt:
                type:
                - string
                - 'null'
            required:
            - company
            - companyDomain
            - companyLogoUrl
            - id
            - status
            - title
            - updatedAt
            additionalProperties: false
        responseRate:
          type: number
          description: Percentage of applied jobs with response
          example: 35.5
        statusCounts:
          type: object
          properties:
            applied:
              type: integer
            archived:
              type: integer
            interviewing:
              type: integer
            offered:
              type: integer
            preparing:
              type: integer
            rejected:
              type: integer
            saved:
              type: integer
          required:
          - applied
          - archived
          - interviewing
          - offered
          - preparing
          - rejected
          - saved
          additionalProperties: false
        topCompanies:
          type: array
          items:
            type: object
            properties:
              company:
                type: string
              companyDomain:
                type:
                - string
                - 'null'
                description: Trusted company-intel domain (company.domain) for the FE logo favicon fallback
              companyLogoUrl:
                type:
                - string
                - 'null'
                description: Company logo URL
              count:
                type: integer
              recentJobTitle:
                type:
                - string
                - 'null'
                description: Most recent job title at this company
            required:
            - company
            - companyDomain
            - companyLogoUrl
            - count
            - recentJobTitle
            additionalProperties: false
          description: Most applied-to companies with recent job title
        totalJobs:
          type: integer
        unactionedHighMatches:
          type: integer
          description: Roles scored 80+ that the user has neither dismissed nor applied to. The one figure on the analytics screen that names a next action.
          example: 942
        weeklyApplications:
          type: integer
          description: Jobs applied this week
      required:
      - atsScoreDistribution
      - avgAtsScore
      - dailyAnswers
      - dailyApplications
      - matchQualityByWeek
      - monthlyApplications
      - outcomes
      - previousWeekApplications
      - recentActivity
      - responseRate
      - statusCounts
      - topCompanies
      - totalJobs
      - unactionedHighMatches
      - weeklyApplications
    BlockerRow:
      type: object
      properties:
        count:
          type: integer
        reason:
          type: string
          enum:
          - geo_restriction
          - stack_mismatch
          - seniority_mismatch
          - onsite_requirement
          - no_response
          - low_match
          - other
          - unknown
          description: Coarse "why this application did not progress" bucket. Used by the pattern-analyzer to surface top blockers and recommendations.
          example: stack_mismatch
        share:
          type: number
          description: 0..1 share of negative outcomes attributable to this blocker
          example: 0.32
      required:
      - count
      - reason
      - share
      additionalProperties: false
    RemotePolicyFunnelRow:
      type: object
      properties:
        conversionRate:
          type: number
        progressed:
          type: integer
        total:
          type: integer
        workArrangement:
          type: string
          enum:
          - onsite
          - hybrid
          - remote_local
          - remote_country
          - remote_region
          - remote_global
          - unknown
          description: How a job can be performed geographically
          example: remote_country
      required:
      - conversionRate
      - progressed
      - total
      - workArrangement
      additionalProperties: false
    RecommendationTemplate:
      oneOf:
      - type: object
        properties:
          kind:
            type: string
            enum:
            - blocker_geo_restriction
          params:
            type: object
            properties:
              count:
                type: integer
                minimum: 0
              sharePercent:
                type: number
                minimum: 0
                maximum: 100
            required:
            - count
            - sharePercent
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - blocker_stack_mismatch
          params:
            type: object
            properties:
              count:
                type: integer
                minimum: 0
              sharePercent:
                type: number
                minimum: 0
                maximum: 100
            required:
            - count
            - sharePercent
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - blocker_seniority_mismatch
          params:
            type: object
            properties:
              count:
                type: integer
                minimum: 0
              sharePercent:
                type: number
                minimum: 0
                maximum: 100
            required:
            - count
            - sharePercent
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - blocker_onsite_requirement
          params:
            type: object
            properties:
              count:
                type: integer
                minimum: 0
              sharePercent:
                type: number
                minimum: 0
                maximum: 100
            required:
            - count
            - sharePercent
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - blocker_no_response
          params:
            type: object
            properties:
              count:
                type: integer
                minimum: 0
              sharePercent:
                type: number
                minimum: 0
                maximum: 100
            required:
            - count
            - sharePercent
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - blocker_low_match
          params:
            type: object
            properties:
              count:
                type: integer
                minimum: 0
              sharePercent:
                type: number
                minimum: 0
                maximum: 100
            required:
            - count
            - sharePercent
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - score_floor_unproven
          params:
            type: object
            properties: {}
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - score_floor_filter
          params:
            type: object
            properties:
              lowBandCeiling:
                type: number
                minimum: 0
              lowBandProgressed:
                type: integer
                minimum: 0
              lowBandTotal:
                type: integer
                minimum: 0
              scoreFloor:
                type: number
                minimum: 0
            required:
            - lowBandCeiling
            - lowBandProgressed
            - lowBandTotal
            - scoreFloor
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - score_floor_prefer
          params:
            type: object
            properties:
              scoreFloor:
                type: number
                minimum: 0
            required:
            - scoreFloor
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - archetype_concentrate
          params:
            type: object
            properties:
              bestArchetype:
                type: string
                enum:
                - software_engineer_frontend
                - software_engineer_backend
                - software_engineer_fullstack
                - software_engineer_mobile
                - software_engineer_embedded
                - software_engineer_games
                - software_engineer_generic
                - devops_sre
                - platform_infra
                - security_engineer
                - qa_test
                - data_engineer
                - data_scientist
                - data_analyst
                - ml_engineer
                - ai_research
                - product_manager
                - project_program_manager
                - designer_product
                - designer_ux_research
                - designer_visual
                - engineering_manager
                - technical_writer
                - developer_advocate
                - solutions_engineer
                - support_engineer
                - sales
                - marketing
                - operations
                - executive
                - finance
                - legal
                - hr_recruiting
                - customer_success
                - healthcare
                - creative-design
                - trades-manual
                - education
                - hospitality
                - logistics-supply
                - manufacturing
                - gov-nonprofit
                - marketing-sales
                - consulting
                - retail
                - insurance
                - admin_office
                - other
                - robotics_engineer
                - control_systems_engineer
                - mechatronics_engineer
                - firmware_engineer
                - fpga_engineer
                - hardware_engineer
                - electrical_engineer
                - rf_engineer
                - analog_engineer
                - biomedical_engineer
                - aerospace_engineer
                - avionics_engineer
                - simulation_engineer
                - computer_vision_engineer
                - autonomous_vehicles_engineer
                - graphics_engineer
                - blockchain_engineer
                - smart_contract_engineer
                - game_designer
                - ios_engineer
                - android_engineer
                - mlops_engineer
                - ai_infrastructure_engineer
                - llm_engineer
                - prompt_engineer
                - research_engineer
                - applied_scientist
                - cloud_architect
                - solutions_architect
                - enterprise_architect
                - release_engineer
                - network_engineer
                - systems_engineer
                - database_administrator
                - appsec_engineer
                - pentest_engineer
                - soc_analyst
                - incident_responder
                - analytics_engineer
                - data_architect
                - bioinformatics_engineer
                - computational_biologist
                - quant_analyst
                - quant_developer
                - trading_systems_engineer
                - risk_analyst
                - sdet
                - automation_engineer
                - product_manager_growth
                - ux_writer
                - content_designer
                - design_engineer
                - documentation_engineer
                - customer_engineer
                - implementation_engineer
                - civil_engineer
                - mechanical_engineer
                description: Canonical role family for matching
                example: software_engineer_frontend
              bestConversionPercent:
                type: number
                minimum: 0
                maximum: 100
              bestProgressed:
                type: integer
                minimum: 0
              bestTotal:
                type: integer
                minimum: 0
              worstArchetype:
                type: string
                enum:
                - software_engineer_frontend
                - software_engineer_backend
                - software_engineer_fullstack
                - software_engineer_mobile
                - software_engineer_embedded
                - software_engineer_games
                - software_engineer_generic
                - devops_sre
                - platform_infra
                - security_engineer
                - qa_test
                - data_engineer
                - data_scientist
                - data_analyst
                - ml_engineer
                - ai_research
                - product_manager
                - project_program_manager
                - designer_product
                - designer_ux_research
                - designer_visual
                - engineering_manager
                - technical_writer
                - developer_advocate
                - solutions_engineer
                - support_engineer
                - sales
                - marketing
                - operations
                - executive
                - finance
                - legal
                - hr_recruiting
                - customer_success
                - healthcare
                - creative-design
                - trades-manual
                - education
                - hospitality
                - logistics-supply
                - manufacturing
                - gov-nonprofit
                - marketing-sales
                - consulting
                - retail
                - insurance
                - admin_office
                - other
                - robotics_engineer
                - control_systems_engineer
                - mechatronics_engineer
                - firmware_engineer
                - fpga_engineer
                - hardware_engineer
                - electrical_engineer
                - rf_engineer
                - analog_engineer
                - biomedical_engineer
                - aerospace_engineer
                - avionics_engineer
                - simulation_engineer
                - computer_vision_engineer
                - autonomous_vehicles_engineer
                - graphics_engineer
                - blockchain_engineer
                - smart_contract_engineer
                - game_designer
                - ios_engineer
                - android_engineer
                - mlops_engineer
                - ai_infrastructure_engineer
                - llm_engineer
                - prompt_engineer
                - research_engineer
                - applied_scientist
                - cloud_architect
                - solutions_architect
                - enterprise_architect
                - release_engineer
                - network_engineer
                - systems_engineer
                - database_administrator
                - appsec_engineer
                - pentest_engineer
                - soc_analyst
                - incident_responder
                - analytics_engineer
                - data_architect
                - bioinformatics_engineer
                - computational_biologist
                - quant_analyst
                - quant_developer
                - trading_systems_engineer
                - risk_analyst
                - sdet
                - automation_engineer
                - product_manager_growth
                - ux_writer
                - content_designer
                - design_engineer
                - documentation_engineer
                - customer_engineer
                - implementation_engineer
                - civil_engineer
                - mechanical_engineer
                description: Canonical role family for matching
                example: software_engineer_frontend
              worstConversionPercent:
                type: number
                minimum: 0
                maximum: 100
              worstProgressed:
                type: integer
                minimum: 0
              worstTotal:
                type: integer
                minimum: 0
            required:
            - bestArchetype
            - bestConversionPercent
            - bestProgressed
            - bestTotal
            - worstArchetype
            - worstConversionPercent
            - worstProgressed
            - worstTotal
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - remote_onsite
          params:
            type: object
            properties:
              progressed:
                type: integer
                minimum: 0
              total:
                type: integer
                minimum: 0
            required:
            - progressed
            - total
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      - type: object
        properties:
          kind:
            type: string
            enum:
            - skill_gap
          params:
            type: object
            properties:
              negativePercent:
                type: number
                minimum: 0
                maximum: 100
              occurrences:
                type: integer
                minimum: 0
              skill:
                type: string
                minLength: 1
            required:
            - negativePercent
            - occurrences
            - skill
            additionalProperties: false
        required:
        - kind
        - params
        additionalProperties: false
      description: Stable catalog template and exact interpolation values for localized clients.
    PatternAnalysisResult:
      oneOf:
      - $ref: '#/components/schemas/PatternAnalysisReady'
      - $ref: '#/components/schemas/PatternAnalysisInsufficient'
      discriminator:
        propertyName: status
        mapping:
          ready: '#/components/schemas/PatternAnalysisReady'
          insufficient_data: '#/components/schemas/PatternAnalysisInsufficient'
    ResponseMetadata:
      type: object
      properties:
        duration:
          type: number
          description: Request duration in milliseconds
          example: 150
          exclusiveMinimum: 0
        performance:
          type: object
          properties:
            dbQueries:
              type: integer
              minimum: 0
            totalDbTime:
              type: number
              minimum: 0
          description: Performance metrics (preview/local only)
        requestId:
          type: string
          description: Unique request identifier
          example: req_abc123
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp
          example: '2026-09-25T17:29:47.224Z'
        version:
          type: string
          description: API version
          example: v1
    ApplyRecommendationRequest:
      oneOf:
      - type: object
        properties:
          actionPayload:
            type: object
            properties:
              threshold:
                type: number
                minimum: 0
                maximum: 100
            required:
            - threshold
            additionalProperties: false
          actionType:
            type: string
            enum:
            - raise_score_floor
        required:
        - actionPayload
        - actionType
        additionalProperties: false
      - type: object
        properties:
          actionPayload:
            type: object
            properties:
              policy:
                type: string
                enum:
                - onsite
                - hybrid
                - remote
                description: User's preferred work style, physical mode only, no geo scoping
                example: remote
            required:
            - policy
            additionalProperties: false
          actionType:
            type: string
            enum:
            - filter_remote_policy
        required:
        - actionPayload
        - actionType
        additionalProperties: false
      - type: object
        properties:
          actionPayload:
            type: object
            properties:
              archetype:
                type: string
                enum:
                - software_engineer_frontend
                - software_engineer_backend
                - software_engineer_fullstack
                - software_engineer_mobile
                - software_engineer_embedded
                - software_engineer_games
                - software_engineer_generic
                - devops_sre
                - platform_infra
                - security_engineer
                - qa_test
                - data_engineer
                - data_scientist
                - data_analyst
                - ml_engineer
                - ai_research
                - product_manager
                - project_program_manager
                - designer_product
                - designer_ux_research
                - designer_visual
                - engineering_manager
                - technical_writer
                - developer_advocate
                - solutions_engineer
                - support_engineer
                - sales
                - marketing
                - operations
                - executive
                - finance
                - legal
                - hr_recruiting
                - customer_success
                - healthcare
                - creative-design
                - trades-manual
                - education
                - hospitality
                - logistics-supply
                - manufacturing
                - gov-nonprofit
                - marketing-sales
                - consulting
                - retail
                - insurance
                - admin_office
                - other
                - robotics_engineer
                - control_systems_engineer
                - mechatronics_engineer
                - firmware_engineer
                - fpga_engineer
                - hardware_engineer
                - electrical_engineer
                - rf_engineer
                - analog_engineer
                - biomedical_engineer
                - aerospace_engineer
                - avionics_engineer
                - simulation_engineer
                - computer_vision_engineer
                - autonomous_vehicles_engineer
                - graphics_engineer
                - blockchain_engineer
                - smart_contract_engineer
                - game_designer
                - ios_engineer
                - android_engineer
                - mlops_engineer
                - ai_infrastructure_engineer
                - llm_engineer
                - prompt_engineer
                - research_engineer
                - applied_scientist
                - cloud_architect
                - solutions_architect
                - enterprise_architect
                - release_engineer
                - network_engineer
                - systems_engineer
                - database_administrator
                - appsec_engineer
                - pentest_engineer
                - soc_analyst
                - incident_responder
                - analytics_engineer
                - data_architect
                - bioinformatics_engineer
                - computational_biologist
                - quant_analyst
                - quant_developer
                - trading_systems_engineer
                - risk_analyst
                - sdet
                - automation_engineer
                - product_manager_growth
                - ux_writer
                - content_designer
                - design_engineer
                - documentation_engineer
                - customer_engineer
                - implementation_engineer
                - civil_engineer
                - mechanical_engineer
                description: Canonical role family for matching
                example: software_engineer_frontend
            required:
            - archetype
            additionalProperties: false
          actionType:
            type: string
            enum:
            - deprioritize_archetype
        required:
        - actionPayload
        - actionType
        additionalProperties: false
      - type: object
        properties:
          actionPayload:
            type: object
            properties: {}
            additionalProperties: false
          actionType:
            type: string
            enum:
            - noop
        required:
        - actionType
        additionalProperties: false
      description: Recommendation action with discriminated payload by actionType.
    ApplyRecommendationResult:
      type: object
      properties:
        changed:
          type: boolean
          description: True when the executor mutated state. False = idempotent no-op (already applied).
        message:
          type: string
          description: Human-readable summary of what happened.
        ok:
          type: boolean
          description: True when the executor accepted + processed the action.
      required:
      - changed
      - message
      - ok
      additionalProperties: false
    SkillGapRow:
      type: object
      properties:
        negativeRate:
          type: number
        occurrences:
          type: integer
          description: Total applications that mention this skill (numerator + denominator union).
        skill:
          type: string
          description: Canonical skill slug (lowercased, kebab-cased) as stored on `job_match.canonical_skills`.
          example: rust
      required:
      - negativeRate
      - occurrences
      - skill
      additionalProperties: false
    ApiErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            context:
              oneOf:
              - type: object
                properties:
                  errorType:
                    type: string
                    enum:
                    - validation
                  field:
                    type: string
                  fieldErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        field:
                          type: string
                        message:
                          type: string
                        received:
                          type: string
                      required:
                      - field
                      - message
                  schemaName:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  attemptedEmail:
                    type: string
                    format: email
                  errorType:
                    type: string
                    enum:
                    - authentication
                  failureReason:
                    type: string
                    enum:
                    - invalid_credentials
                    - account_locked
                    - expired_token
                    - token_expired
                    - missing_token
                    - invalid_token
                    - session_expired
                    description: Reason for authentication failure
                    example: token_expired
                  ipAddress:
                    type: string
                  operation:
                    type: string
                  service:
                    type: string
                  userAgent:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  actualPermission:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - authorization
                  requiredPermission:
                    type: string
                  resource:
                    type: string
                  resourceId:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  constraint:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - database
                  operation:
                    type: string
                    enum:
                    - insert
                    - update
                    - delete
                    - select
                    - batch
                    - transaction
                    - migration
                    description: Type of database operation
                    example: select
                  resourceId:
                    type: string
                  sqlState:
                    type: string
                  table:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  endpoint:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - external_service
                  httpStatus:
                    type: number
                  operation:
                    type: string
                  resourceId:
                    type: string
                  responseTime:
                    type: number
                  retryAttempt:
                    type: integer
                  service:
                    type: string
                  serviceName:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  errorType:
                    type: string
                    enum:
                    - resource
                  resource:
                    type: string
                  resourceId:
                    type: string
                  service:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  errorType:
                    type: string
                    enum:
                    - rate_limit
                  limit:
                    type: number
                  resetTime:
                    type: string
                  windowMs:
                    type: number
                required:
                - errorType
              - type: object
                properties:
                  configKey:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - configuration
                  operation:
                    type: string
                  service:
                    type: string
                required:
                - errorType
              description: Type-safe error context information
              example:
                errorType: validation
                fieldErrors:
                - field: email
                  message: Invalid email format
            details:
              oneOf:
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - validation
                  validationErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        field:
                          type: string
                        message:
                          type: string
                      required:
                      - field
                      - message
                required:
                - detailType
                - validationErrors
                additionalProperties: false
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - service_error
                  originalError:
                    type: string
                  serviceName:
                    type: string
                required:
                - detailType
                - serviceName
                additionalProperties: false
              - type: object
                properties:
                  currentSize:
                    type: number
                  detailType:
                    type: string
                    enum:
                    - batch
                  originalError:
                    type: string
                  statementCount:
                    type: number
                required:
                - detailType
                additionalProperties: false
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - rate_limit
                  limit:
                    type: number
                  resetTime:
                    type: string
                  windowMs:
                    type: number
                required:
                - detailType
                - limit
                - resetTime
                - windowMs
                additionalProperties: false
              - type: object
                properties:
                  conflictingField:
                    type: string
                  detailType:
                    type: string
                    enum:
                    - resource
                  resourceId:
                    anyOf:
                    - type: string
                    - type: number
                  resourceType:
                    type: string
                required:
                - detailType
                additionalProperties: false
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - generic
                  info:
                    type: string
                required:
                - detailType
                additionalProperties: false
              - type: object
                properties:
                  currentTokens:
                    type: integer
                    minimum: 0
                  detailType:
                    type: string
                    enum:
                    - insufficient_tokens
                  requiredTokens:
                    type: integer
                    minimum: 0
                required:
                - currentTokens
                - detailType
                - requiredTokens
                additionalProperties: false
            message:
              type: string
            validation:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                - field
                - message
                additionalProperties: false
          required:
          - code
          - message
          additionalProperties: false
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - false
      required:
      - error
      - success
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      description: 'Session token from signing in to AI Applyd, sent as `Authorization: Bearer <token>`.'
      scheme: bearer
      type: http