# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Aiapplyd Job Matches API
  version: 1.0.0
extends: openapi/aiapplyd-job-matches-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 16
- target: $.paths['/job-matches/preferences'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my job match preferences
      effect: read
      questions:
      - What roles, locations and salary range are my job matches based on?
      - Which preferences is the matcher currently using for me?
      instructions:
      - text: Show my job match preferences.
      - text: Tell me what target roles and locations my matching is set to.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/preferences'].put
  update:
    x-apievangelist-phrasing:
      intent: Update my job match preferences
      effect: write
      questions:
      - How do I change the roles and locations I get matched to?
      - Can I set a minimum salary or require visa sponsorship for my matches?
      - Is it possible to exclude certain industries from my job matches?
      instructions:
      - text: Set my target roles to {targetRoles}.
        slots:
          targetRoles: requestBody.targetRoles
      - text: Only match me to jobs paying at least {salaryMin} {salaryCurrency}.
        slots:
          salaryMin: requestBody.salaryMin
          salaryCurrency: requestBody.salaryCurrency
      - text: Exclude the industries {excludeIndustries} from my matches.
        slots:
          excludeIndustries: requestBody.excludeIndustries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches'].get
  update:
    x-apievangelist-phrasing:
      intent: List today's job matches
      effect: read
      questions:
      - What jobs has AI matched me with today?
      - Can I see only the job matches I've saved?
      instructions:
      - text: List my job matches for today.
      - text: Show only my saved job matches.
      - text: Show the next {limit} job matches after cursor {cursor}.
        slots:
          limit: query.limit
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/work-style-supply'].get
  update:
    x-apievangelist-phrasing:
      intent: See how many jobs my work-style choice allows
      effect: read
      questions:
      - Why am I seeing so few matches with remote-only selected?
      - How many more jobs would I see if I included onsite roles?
      instructions:
      - text: Count how many live jobs my remote/onsite preference admits and excludes.
      - text: Show the job supply my current work-style setting leaves out.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one job match
      effect: read
      questions:
      - Can I pull up the details of a single job match?
      - What does one specific match in my feed contain?
      instructions:
      - text: Show job match {id}.
        slots:
          id: path.id
      - text: Get the details of my job match {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/{id}/save'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a job match to my listings
      effect: write
      questions:
      - How do I save a job match so it becomes a tracked listing?
      - Can I mark a match as already applied when I save it?
      instructions:
      - text: Save job match {id}.
        slots:
          id: path.id
      - text: Save job match {id} with listing status {listingStatus}.
        slots:
          id: path.id
          listingStatus: requestBody.listingStatus
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/{id}/dismiss'].post
  update:
    x-apievangelist-phrasing:
      intent: Dismiss a job match
      effect: write
      questions:
      - How do I hide a job match I'm not interested in?
      - Can I give a reason when I pass on a match?
      instructions:
      - text: Dismiss job match {id}.
        slots:
          id: path.id
      - text: Dismiss job match {id} because {dismissReason}.
        slots:
          id: path.id
          dismissReason: requestBody.dismissReason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/subscribe-cell'].post
  update:
    x-apievangelist-phrasing:
      intent: Get notified when a role opens in a country
      effect: write
      questions:
      - Can I be emailed when jobs for a role family start showing up in my country?
      - What happens if there are no jobs yet for my role in a given country?
      instructions:
      - text: Notify me when {roleFamily} jobs appear in {country}.
        slots:
          roleFamily: requestBody.roleFamily
          country: requestBody.country
      - text: Subscribe me to alerts for role family {roleFamily} in country {country}.
        slots:
          roleFamily: requestBody.roleFamily
          country: requestBody.country
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/validate-role'].post
  update:
    x-apievangelist-phrasing:
      intent: Check if a job title I typed is a real role
      effect: read
      questions:
      - Will the matcher recognize a job title I type in my own language?
      - Which role family does a custom job title map to, and is it misspelled?
      instructions:
      - text: Validate the job title {title} and show its role family.
        slots:
          title: requestBody.title
      - text: Check whether {title} is a real job and suggest a spelling fix if needed.
        slots:
          title: requestBody.title
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/request-more'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a fresh batch of job matches
      effect: write
      questions:
      - I've gone through all my matches — can I ask for more?
      - Is there a cooldown on asking for new matches?
      instructions:
      - text: Find me more job matches now.
      - text: Refill my empty discover feed with new matches.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/apply-relaxation'].post
  update:
    x-apievangelist-phrasing:
      intent: Keep the widened match criteria
      effect: write
      questions:
      - How do I keep the broader matches that were suggested when my feed ran dry?
      - Can the widened search settings be saved to my preferences permanently?
      instructions:
      - text: Keep these widened matches coming by saving the relaxation to my preferences.
      - text: Apply the suggested relaxation to my saved match preferences.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/revert-widening'].post
  update:
    x-apievangelist-phrasing:
      intent: Undo widening and tighten my match feed
      effect: destructive
      questions:
      - Can I undo the widened feed and go back to strictly my chosen roles and countries?
      - Will undoing the widening remove matches I already saved?
      instructions:
      - text: Undo the match widening and tighten my feed to strict preferences.
      - text: Remove the untouched widened matches outside my chosen roles and countries.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/reset'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset all job matches to undiscovered
      effect: destructive
      questions:
      - Can I start my match feed over and clear everything I saved or dismissed?
      - What gets deleted when all matches are reset?
      instructions:
      - text: Reset all my job matches back to the discover feed.
      - text: Clear saved, dismissed and seen flags on every match and delete the linked listings.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/{id}/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a detailed evaluation of a job match
      effect: write
      questions:
      - Can I get a full report on how well I fit a job, including comp and interview plan?
      - Is it possible to regenerate a match evaluation that already exists?
      instructions:
      - text: Start the A-G evaluation report for job match {id}.
        slots:
          id: path.id
      - text: Regenerate the evaluation for job match {id} with force set to {force}.
        slots:
          id: path.id
          force: query.force
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/{id}/evaluation'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the saved evaluation for a job match
      effect: read
      questions:
      - Is the evaluation report for my job match ready yet?
      - What did the A-G evaluation say about my CV fit for a job?
      instructions:
      - text: Show the evaluation results for job match {id}.
        slots:
          id: path.id
      - text: Get the finished A-G report blocks for match {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/job-matches/{id}/verify-live'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a job match posting is still live
      effect: write
      questions:
      - Is the job posting behind this match still open before I apply?
      - What happens if a matched listing turns out to be dead?
      instructions:
      - text: Verify that job match {id} is still live.
        slots:
          id: path.id
      - text: Check if the posting for match {id} has been taken down.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'