API Evangelist conversational phrasing for Files API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Files API
  version: 1.0.0
extends: openapi/hubspot-files-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 12
- target: $.paths['/files/2026-03/files'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a file to the file manager
      effect: write
      questions:
      - How do I upload an image from my computer into the HubSpot file manager?
      - Can I choose which folder an uploaded file lands in?
      instructions:
      - text: Upload {file} to the file manager as {fileName}.
        slots:
          file: requestBody.file
          fileName: requestBody.fileName
      - text: Upload {file} into folder path {folderPath}.
        slots:
          file: requestBody.file
          folderPath: requestBody.folderPath
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/files/import-from-url/async'].post
  update:
    x-apievangelist-phrasing:
      intent: Import a file from a URL
      effect: write
      questions:
      - Can I pull a file into the file manager straight from a web address?
      - What happens if a file I import from a URL already exists in the folder?
      - Can an imported file expire automatically after a set time?
      instructions:
      - text: Import the file at {url} into folder {folderPath} with {access} access.
        slots:
          url: requestBody.url
          folderPath: requestBody.folderPath
          access: requestBody.access
      - text: Fetch {url} into the file manager as {name}, rejecting duplicates by {duplicateValidationStrategy}.
        slots:
          url: requestBody.url
          name: requestBody.name
          duplicateValidationStrategy: requestBody.duplicateValidationStrategy
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/files/import-from-url/async/tasks/{taskId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a URL import's status
      effect: read
      questions:
      - Has my import-from-URL file task finished yet?
      - Where do I check whether an asynchronous file import succeeded?
      instructions:
      - text: Check the status of file import task {taskId}.
        slots:
          taskId: path.taskId
      - text: Tell me whether URL import {taskId} is complete.
        slots:
          taskId: path.taskId
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/files/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search files in the file manager
      effect: read
      questions:
      - How do I find all PDFs in my file manager?
      - Can I search for images wider than a certain number of pixels?
      - Which files are larger than a given size?
      instructions:
      - text: Search the file manager for files named {name}.
        slots:
          name: query.name
      - text: Find files with extension {extension} created after {createdAtGte}.
        slots:
          extension: query.extension
          createdAtGte: query.createdAtGte
      - text: Search for files over {sizeGte} bytes.
        slots:
          sizeGte: query.sizeGte
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/files/stat/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a file by its path
      effect: read
      questions:
      - I know where a file lives in my folders; how do I get its details from that path?
      - Can I fetch file metadata using a folder path instead of an ID?
      instructions:
      - text: Get the file at path {path}.
        slots:
          path: path.path
      - text: Show metadata for the file stored at {path}.
        slots:
          path: path.path
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/files/{fileId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a file by ID
      effect: read
      questions:
      - How do I get a file's details when I have its file ID?
      - What properties can I read on a single file by ID?
      instructions:
      - text: Get file {fileId}.
        slots:
          fileId: path.fileId
      - text: Retrieve file {fileId} with properties {properties}.
        slots:
          fileId: path.fileId
          properties: query.properties
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/files/{fileId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a file's contents
      effect: write
      questions:
      - Can I swap an image's content without breaking every page that links to it?
      - How do I overwrite an existing file with a new version while keeping the same ID?
      instructions:
      - text: Replace the contents of file {fileId} with {file}.
        slots:
          fileId: path.fileId
          file: requestBody.file
      - text: Swap in new image data {file} for existing file {fileId}.
        slots:
          file: requestBody.file
          fileId: path.fileId
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/files/{fileId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a file
      effect: destructive
      questions:
      - How do I remove a file I no longer need from the file manager?
      - Is a standard file delete the same as a GDPR delete?
      instructions:
      - text: Delete file {fileId}.
        slots:
          fileId: path.fileId
      - text: Remove file {fileId} from the file manager with a normal delete.
        slots:
          fileId: path.fileId
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/files/{fileId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a file's properties
      effect: write
      questions:
      - Can I rename a file or move it to another folder?
      - How do I stop a file from being offered in new content?
      - Can I clear the expiration date on a file?
      instructions:
      - text: Rename file {fileId} to {name}.
        slots:
          fileId: path.fileId
          name: requestBody.name
      - text: Move file {fileId} to folder {parentFolderPath}.
        slots:
          fileId: path.fileId
          parentFolderPath: requestBody.parentFolderPath
      - text: 'Mark file {fileId} as usable in content: {isUsableInContent}.'
        slots:
          fileId: path.fileId
          isUsableInContent: requestBody.isUsableInContent
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/files/{fileId}/gdpr-delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: GDPR-delete a file
      effect: destructive
      questions:
      - How do I permanently erase a file to meet a GDPR request?
      - Is there a delete that satisfies GDPR rules for personal files?
      instructions:
      - text: GDPR-delete file {fileId}.
        slots:
          fileId: path.fileId
      - text: Erase file {fileId} in accordance with GDPR.
        slots:
          fileId: path.fileId
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/files/{fileId}/signed-url'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a temporary link to a private file
      effect: read
      questions:
      - How can I share a private file temporarily without making it public?
      - Can I control how long a signed file link stays valid?
      instructions:
      - text: Generate a signed URL for private file {fileId}.
        slots:
          fileId: path.fileId
      - text: Create a signed link to {fileId} that expires in {expirationSeconds} seconds.
        slots:
          fileId: path.fileId
          expirationSeconds: query.expirationSeconds
      method: generated
      generated: '2026-09-24'
- target: $.paths['/files/2026-03/folders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a folder
      effect: write
      questions:
      - How do I make a new folder in the file manager?
      - Can I create a folder inside an existing folder?
      instructions:
      - text: Create a folder named {name}.
        slots:
          name: requestBody.name
      - text: Create folder {name} under parent path {parentPath}.
        slots:
          name: requestBody.name
          parentPath: requestBody.parentPath
      method: generated
      generated: '2026-09-24'