API Evangelist conversational phrasing for Reference Pulls API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Reference Pulls API
  version: 1.0.0
extends: openapi/canopy-pulls-api-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 8
- target: $.paths['/teams/{teamId}/pulls/{pullId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get all data for a pull
      effect: read
      questions:
      - How do I fetch everything collected from a consumer's insurance connection?
      - Can I also get property data when retrieving a single pull?
      instructions:
      - text: Get pull {pull} on team {team}.
        slots:
          pull: path.pullId
          team: path.teamId
      - text: 'Fetch pull {pull} and include property data: {prop}.'
        slots:
          pull: path.pullId
          prop: query.withPropertyData
      method: generated
      generated: '2026-10-01'
- target: $.paths['/teams/{teamId}/pulls/{pullId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Archive or unarchive a pull
      effect: write
      questions:
      - How do I archive a pull I no longer need to see?
      - Can I restore an archived pull?
      instructions:
      - text: Archive pull {pull} on team {team}.
        slots:
          pull: path.pullId
          team: path.teamId
      - text: Set archived to {archived} on pull {pull}.
        slots:
          archived: requestBody.is_archived
          pull: path.pullId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/teams/{teamId}/pulls'].get
  update:
    x-apievangelist-phrasing:
      intent: List a team's pulls
      effect: read
      questions:
      - Which insurance pulls has my team received recently?
      - Can I list pulls between two dates?
      - How do I page through pulls with a limit and offset?
      instructions:
      - text: List the pulls on team {team}.
        slots:
          team: path.teamId
      - text: List pulls on team {team} since {since}.
        slots:
          team: path.teamId
          since: query.since
      - text: Show {limit} pulls starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/teams/{teamId}/pulls/{pullId}/documents/{documentId}/pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a pull document PDF (deprecated)
      effect: read
      questions:
      - Is there a legacy PDF route for downloading a document from a pull?
      - What replaced the deprecated document PDF download endpoint?
      instructions:
      - text: Download document {document} from pull {pull} on team {team} as a PDF using the deprecated route.
        slots:
          document: path.documentId
          pull: path.pullId
          team: path.teamId
      - text: Stream the PDF of document {document} through the older pdf endpoint.
        slots:
          document: path.documentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/teams/{teamId}/pulls/{pullId}/documents/{documentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a document from a pull
      effect: read
      questions:
      - How do I download an insurance document like a declarations page from a pull?
      - Does a document download return a short-lived signed link?
      instructions:
      - text: Download document {document} from pull {pull} on team {team}.
        slots:
          document: path.documentId
          pull: path.pullId
          team: path.teamId
      - text: Get the signed download link for document {document} on pull {pull}.
        slots:
          document: path.documentId
          pull: path.pullId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/teams/{teamId}/pulls/{pullId}/answers/{answerId}/files/{fileId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a file the consumer uploaded
      effect: read
      questions:
      - How can I get a file a consumer uploaded in answer to a question?
      - Where do I download files from a file upload answer on a pull?
      instructions:
      - text: Download file {file} from answer {answer} on pull {pull} for team {team}.
        slots:
          file: path.fileId
          answer: path.answerId
          pull: path.pullId
          team: path.teamId
      - text: Get the consumer's uploaded file {file} attached to answer {answer}.
        slots:
          file: path.fileId
          answer: path.answerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/teams/{teamId}/pulls/{pullId}/policyCheck'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a Policy Check on a pull
      effect: write
      questions:
      - How do I evaluate a Policy Check against one specific pull?
      - Can I restrict which entities a Policy Check evaluates on a pull?
      instructions:
      - text: Run a Policy Check on pull {pull} for team {team}.
        slots:
          pull: path.pullId
          team: path.teamId
      - text: Evaluate pull {pull} with Policy Check settings {settings} limited by {filters}.
        slots:
          pull: path.pullId
          settings: requestBody.policy_check_settings
          filters: requestBody.filters
      method: generated
      generated: '2026-10-01'
- target: $.paths['/teams/{teamId}/pulls/{pullId}/policyCheck/pdf'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a pull's Policy Check PDF
      effect: read
      questions:
      - Can I get the Policy Check results for a pull as a PDF report?
      - Where do I download the Policy Check report for a pull?
      instructions:
      - text: Download the Policy Check PDF for pull {pull} on team {team}.
        slots:
          pull: path.pullId
          team: path.teamId
      - text: Get the Policy Check report PDF of pull {pull}.
        slots:
          pull: path.pullId
      method: generated
      generated: '2026-10-01'