# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Aiapplyd Jobs API
  version: 1.0.0
extends: openapi/aiapplyd-jobs-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: 18
- target: $.paths['/jobs/extract-keywords'].post
  update:
    x-apievangelist-phrasing:
      intent: Extract ATS keywords from a job description
      effect: read
      questions:
      - Which skills and keywords does an ATS look for in a job description?
      - Can I pull the key terms out of a job posting's text?
      instructions:
      - text: 'Extract ATS keywords from this job description: {jobDescription}.'
        slots:
          jobDescription: requestBody.jobDescription
      - text: List the skills mentioned in {jobDescription}.
        slots:
          jobDescription: requestBody.jobDescription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/compare'].post
  update:
    x-apievangelist-phrasing:
      intent: Compare several job offers side by side
      effect: read
      questions:
      - Can I compare two to five job listings side by side?
      - Which of my saved jobs scores best across salary, growth and other dimensions?
      instructions:
      - text: Compare jobs {jobIds} side by side.
        slots:
          jobIds: requestBody.jobIds
      - text: Score and rank the job listings {jobIds} against my resume.
        slots:
          jobIds: requestBody.jobIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/parse-url'].post
  update:
    x-apievangelist-phrasing:
      intent: Parse a job posting URL into structured data
      effect: read
      questions:
      - Can I turn a job posting link into structured job details without saving it?
      - What details can be extracted from a job URL?
      instructions:
      - text: Parse the job posting at {url}.
        slots:
          url: requestBody.url
      - text: Extract the title, company and requirements from {url}.
        slots:
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/import-url'].post
  update:
    x-apievangelist-phrasing:
      intent: Import a job into my feed from its apply URL
      effect: write
      questions:
      - How do I add a job to my feed from a company's application page link?
      - Why was my LinkedIn or Indeed job link rejected when importing?
      instructions:
      - text: Import the job at {url} into my feed.
        slots:
          url: requestBody.url
      - text: Add the posting from direct application link {url} to my jobs.
        slots:
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/ats-scores/{atsScoreId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one ATS score result
      effect: read
      questions:
      - Is my ATS score analysis finished yet?
      - Where can I see a single ATS score by its id?
      instructions:
      - text: Get ATS score {atsScoreId}.
        slots:
          atsScoreId: path.atsScoreId
      - text: Check the status of ATS score run {atsScoreId}.
        slots:
          atsScoreId: path.atsScoreId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my job tracking stats
      effect: read
      questions:
      - How many jobs did I apply to today and this week?
      - How many of my tracked jobs have ghosted me or reached interviews?
      instructions:
      - text: Show my job listing stats.
      - text: Give me counts of tracked, ghosted and interviewing jobs.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List my tracked job listings
      effect: read
      questions:
      - Which jobs am I currently tracking?
      - Can I search my saved job listings by keyword and sort them?
      instructions:
      - text: List my tracked job listings.
      - text: Find my saved jobs matching {search} with status {status}.
        slots:
          search: query.search
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a new job listing to track
      effect: write
      questions:
      - How do I add a job I found myself so I can track it and score my resume?
      - What happens if I save the same posting URL twice?
      instructions:
      - text: 'Track a new job: {title}, description {description}.'
        slots:
          title: requestBody.title
          description: requestBody.description
      - text: Create a job listing {title} at {company} from {sourceUrl} with description {description}.
        slots:
          title: requestBody.title
          company: requestBody.company
          sourceUrl: requestBody.sourceUrl
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one tracked job listing
      effect: read
      questions:
      - Where can I see the full details of one job I'm tracking?
      - What does it mean when a job listing returns gone?
      instructions:
      - text: Show job listing {id}.
        slots:
          id: path.id
      - text: Get the details of tracked job {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a tracked job listing
      effect: write
      questions:
      - Can I change the salary or location on a job I'm already tracking?
      - Can I update the status of an existing job listing?
      instructions:
      - text: Update job {id} with salary {salary}.
        slots:
          id: path.id
          salary: requestBody.salary
      - text: Change the title of job listing {id} to {title}.
        slots:
          id: path.id
          title: requestBody.title
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tracked job listing
      effect: destructive
      questions:
      - Can I remove a job from my tracker?
      - Are the ATS scores deleted when I delete a job listing?
      instructions:
      - text: Delete job listing {id}.
        slots:
          id: path.id
      - text: Remove job {id} and its ATS scores.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{id}/ats-score'].post
  update:
    x-apievangelist-phrasing:
      intent: Score a document against a job's ATS
      effect: write
      questions:
      - How well does my resume match a specific job's ATS?
      - Can I run an ATS compatibility check for one of my documents against a saved job?
      instructions:
      - text: Run an ATS score for document {userDocumentId} against job {id}.
        slots:
          userDocumentId: requestBody.userDocumentId
          id: path.id
      - text: Check how resume {userDocumentId} scores on job {id}.
        slots:
          userDocumentId: requestBody.userDocumentId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{id}/ats-scores'].get
  update:
    x-apievangelist-phrasing:
      intent: List all ATS scores for a job
      effect: read
      questions:
      - What ATS scores have I run for a particular job?
      - Can I see every past ATS score for one listing?
      instructions:
      - text: List the ATS scores for job {id}.
        slots:
          id: path.id
      - text: Show all ATS results run on job listing {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{id}/generate-interview-prep'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate interview prep for a job
      effect: write
      questions:
      - Can I get AI interview preparation for a specific job?
      - How do I retry interview prep generation that failed?
      instructions:
      - text: Generate interview prep for job {id}.
        slots:
          id: path.id
      - text: 'Retry interview prep for job {id}: {retry}.'
        slots:
          id: path.id
          retry: requestBody.retry
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{id}/generate-all'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate prep, compensation and match report at once
      effect: write
      questions:
      - Can I kick off interview prep, comp intelligence and the match report together?
      - How do I generate the full timeline for a saved job in one action?
      instructions:
      - text: Generate everything for job {id}.
        slots:
          id: path.id
      - text: Kick off the full job timeline for {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{id}/comp-intelligence'].post
  update:
    x-apievangelist-phrasing:
      intent: Analyze compensation for a job
      effect: write
      questions:
      - What salary range and negotiation leverage should I expect for a job?
      - How strong is market demand for a role I'm considering?
      instructions:
      - text: 'Analyze compensation for job {id}: {jobTitle} at {company}, description {jobDescription}.'
        slots:
          id: path.id
          jobTitle: requestBody.jobTitle
          company: requestBody.company
          jobDescription: requestBody.jobDescription
      - text: Get comp intelligence for {jobTitle} at {company} in {location} for job {id} using {jobDescription}.
        slots:
          jobTitle: requestBody.jobTitle
          company: requestBody.company
          location: requestBody.location
          id: path.id
          jobDescription: requestBody.jobDescription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{id}/stage'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the hiring stage on a tracked job
      effect: write
      questions:
      - How do I mark a tracked job as interviewing in my tracker?
      - Can I move a saved job listing to the offered stage?
      instructions:
      - text: Set job listing {id} to stage {applicationStage}.
        slots:
          id: path.id
          applicationStage: requestBody.applicationStage
      - text: Move tracked job {id} to offered.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{id}/ghosting-status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a job has ghosted me
      effect: read
      questions:
      - Has a company ghosted me after my application?
      - How long since I last heard back from a job by email?
      instructions:
      - text: Check the ghosting status of job {id}.
        slots:
          id: path.id
      - text: Tell me if job {id} has gone quiet.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'