# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Aiapplyd User Documents API
  version: 1.0.0
extends: openapi/aiapplyd-user-documents-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: 19
- target: $.paths['/user-documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List my saved documents
      effect: read
      questions:
      - Which resumes and cover letters have I uploaded?
      - Can I filter my saved documents to just one type, like cover letters?
      instructions:
      - text: List all my saved documents.
      - text: Show my documents of type {type}.
        slots:
          type: query.type
      - text: Show page {page} of my documents, {limit} per page.
        slots:
          page: query.page
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a document record
      effect: write
      questions:
      - How do I create a new document entry before uploading its file?
      - Can I create a temporary document that isn't kept long-term?
      instructions:
      - text: Create a {documentType} document titled {title}.
        slots:
          documentType: requestBody.documentType
          title: requestBody.title
      - text: Add a temporary {documentType} document record named {title}.
        slots:
          documentType: requestBody.documentType
          title: requestBody.title
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/translate-preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a file translation without saving
      effect: read
      questions:
      - Can I see what my resume looks like translated before I save anything?
      - Is there a try-it translation for an uploaded file into several languages at once?
      instructions:
      - text: Translate {file} into {targetLanguages} as a preview, without saving it.
        slots:
          file: requestBody.file
          targetLanguages: requestBody.targetLanguages
      - text: Show me a temporary translation of this upload into {targetLanguages}.
        slots:
          targetLanguages: requestBody.targetLanguages
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/save-translation'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a translation preview as a document
      effect: write
      questions:
      - How do I keep a translation preview I liked as a real document?
      - Does saving a translated preview also generate a PDF?
      instructions:
      - text: Save this translated text {contentMarkdown} as a new document titled {title}.
        slots:
          contentMarkdown: requestBody.contentMarkdown
          title: requestBody.title
      - text: 'Keep the translation preview as document {title} with a generated PDF: {contentMarkdown}.'
        slots:
          title: requestBody.title
          contentMarkdown: requestBody.contentMarkdown
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/ats-score-preview'].post
  update:
    x-apievangelist-phrasing:
      intent: ATS-score an uploaded file without saving
      effect: read
      questions:
      - Can I get an ATS score for a resume file without adding it to my documents?
      - What would an unsaved resume upload score against a job posting?
      instructions:
      - text: Score the file {file} for ATS compatibility without saving it.
        slots:
          file: requestBody.file
      - text: 'Give a throwaway ATS score for {file} against this job description: {jobDescription}.'
        slots:
          file: requestBody.file
          jobDescription: requestBody.jobDescription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/ats-optimize-preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview ATS-optimized content for an upload
      effect: read
      questions:
      - Can I see an ATS-optimized version of a resume file before committing to it?
      - Is it possible to optimize an uploaded resume for a job without storing the result?
      instructions:
      - text: Show an ATS-optimized preview of {file} without saving.
        slots:
          file: requestBody.file
      - text: 'Preview how {file} would be rewritten for this job description: {jobDescription}.'
        slots:
          file: requestBody.file
          jobDescription: requestBody.jobDescription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}/parse-status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a resume has finished parsing
      effect: read
      questions:
      - Has the AI finished reading the resume I just uploaded?
      - When is a document's parsed data ready to use?
      instructions:
      - text: Check the parse status of document {id}.
        slots:
          id: path.id
      - text: Poll whether document {id} is parsed and return its data if ready.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one saved document
      effect: read
      questions:
      - Can I look up the details of a single saved document?
      - What title and type does a particular document of mine have?
      instructions:
      - text: Show me document {id}.
        slots:
          id: path.id
      - text: Get the metadata for my document {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or retype a saved document
      effect: write
      questions:
      - How do I rename one of my uploaded documents?
      - Can I change a document's type or edit its markdown content?
      instructions:
      - text: Rename document {id} to {title}.
        slots:
          id: path.id
          title: requestBody.title
      - text: Change the type of document {id} to {documentType}.
        slots:
          id: path.id
          documentType: requestBody.documentType
      - text: Replace the content of document {id} with {contentMarkdown}.
        slots:
          id: path.id
          contentMarkdown: requestBody.contentMarkdown
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a saved document and its file
      effect: destructive
      questions:
      - How can I delete an uploaded resume along with its stored file?
      - Does removing a document also delete the file behind it?
      instructions:
      - text: Delete document {id} and its file.
        slots:
          id: path.id
      - text: Permanently remove my saved document {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}/set-base'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a document as my base for its type
      effect: write
      questions:
      - How do I set which uploaded resume is my base resume?
      - Can I have more than one base document per type?
      instructions:
      - text: Set document {id} as my base document for its type.
        slots:
          id: path.id
      - text: Make {id} my base resume.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}/upload'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a file to a document record
      effect: write
      questions:
      - What file types and size can I upload to a document?
      - How do I attach a PDF or DOCX to a document record I created?
      instructions:
      - text: Upload {file} to document {id}.
        slots:
          file: requestBody.file
          id: path.id
      - text: Attach this PDF {file} to my document record {id}.
        slots:
          file: requestBody.file
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}/download'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a saved document's file
      effect: read
      questions:
      - Can I download the original file of a document I uploaded?
      - Where do I get the PDF behind one of my saved documents?
      instructions:
      - text: Download the file for document {id}.
        slots:
          id: path.id
      - text: Fetch the stored file of my document {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}/translate'].post
  update:
    x-apievangelist-phrasing:
      intent: Translate a saved document into other languages
      effect: write
      questions:
      - Can AI translate a document I've already saved and keep the copies?
      - Does translating a saved document make a new copy for each language?
      instructions:
      - text: Translate saved document {id} into {targetLanguage}.
        slots:
          id: path.id
          targetLanguage: requestBody.targetLanguage
      - text: Create translated copies of document {id} in {targetLanguages}.
        slots:
          id: path.id
          targetLanguages: requestBody.targetLanguages
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}/tailor'].post
  update:
    x-apievangelist-phrasing:
      intent: Tailor a resume document to a job listing
      effect: write
      questions:
      - Can AI tailor one of my uploaded resumes to a specific job listing?
      - Does tailoring a resume overwrite the original or create a new copy?
      instructions:
      - text: Tailor document {id} for job listing {jobListingId}.
        slots:
          id: path.id
          jobListingId: requestBody.jobListingId
      - text: Make a tailored copy of resume {id} aimed at job listing {jobListingId}.
        slots:
          id: path.id
          jobListingId: requestBody.jobListingId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}/ats-score'].post
  update:
    x-apievangelist-phrasing:
      intent: ATS-score a saved resume document
      effect: read
      questions:
      - What ATS score does a resume I've already uploaded get?
      - Can I score a saved resume document against a particular job description?
      instructions:
      - text: 'Score saved document {id} for ATS against this job description: {jobDescription}.'
        slots:
          id: path.id
          jobDescription: requestBody.jobDescription
      - text: Check the ATS compatibility of my uploaded resume {id} for {jobDescription}.
        slots:
          id: path.id
          jobDescription: requestBody.jobDescription
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}/ats-optimize'].post
  update:
    x-apievangelist-phrasing:
      intent: ATS-optimize a saved resume document
      effect: write
      questions:
      - Can AI improve the ATS compatibility of a resume I uploaded and re-score it?
      - Is there an option to apply ATS changes directly to a saved document?
      instructions:
      - text: Optimize saved document {id} for ATS.
        slots:
          id: path.id
      - text: 'Optimize document {id} for this job description {jobDescription} and apply the changes: {apply}.'
        slots:
          id: path.id
          jobDescription: requestBody.jobDescription
          apply: requestBody.apply
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/{id}/share'].post
  update:
    x-apievangelist-phrasing:
      intent: Share or unshare a saved document
      effect: write
      questions:
      - How do I make one of my uploaded documents viewable by link?
      - Can I stop publicly sharing a document I uploaded?
      instructions:
      - text: Turn on public sharing for document {id}.
        slots:
          id: path.id
      - text: Set public sharing on uploaded document {id} to {isPublic}.
        slots:
          id: path.id
          isPublic: requestBody.isPublic
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user-documents/shared/{token}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a publicly shared document
      effect: read
      questions:
      - Can I open a shared document link without logging in?
      - Is it possible to include the content when viewing a shared document?
      instructions:
      - text: Open the shared document with token {token}.
        slots:
          token: path.token
      - text: 'View shared document {token} including its content: {content}.'
        slots:
          token: path.token
          content: query.content
      method: generated
      generated: '2026-09-26'