# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Reference Files API
  version: 1.0.0
extends: openapi/lightfield-files-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: 6
- target: $.paths['/v1/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List workspace files
      effect: read
      questions:
      - How do I see all the files uploaded to my workspace?
      - Can I page through my workspace files a batch at a time?
      instructions:
      - text: List the files in my workspace.
      - text: List {limit} files starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/files'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a file upload and get an upload URL
      effect: write
      questions:
      - How do I upload a file, such as a meeting transcript, to Lightfield?
      - Can I check a file's MIME type and size against its purpose before uploading the bytes?
      instructions:
      - text: Start an upload for {filename} of type {mimeType}, {sizeBytes} bytes.
        slots:
          filename: requestBody.filename
          mimeType: requestBody.mimeType
          sizeBytes: requestBody.sizeBytes
      - text: Get an upload URL for {filename} ({mimeType}, {sizeBytes} bytes) for purpose {purpose}.
        slots:
          filename: requestBody.filename
          mimeType: requestBody.mimeType
          sizeBytes: requestBody.sizeBytes
          purpose: requestBody.purpose
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/files/{id}/complete'].post
  update:
    x-apievangelist-phrasing:
      intent: Finalize a file upload
      effect: write
      questions:
      - What do I call after the file bytes have finished uploading?
      - Can the server verify an MD5 checksum when I finish an upload?
      instructions:
      - text: Mark the upload for file {id} as complete.
        slots:
          id: path.id
      - text: Finalize file {id} and verify its checksum {md5}.
        slots:
          id: path.id
          md5: requestBody.md5
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/files/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a file's details and status
      effect: read
      questions:
      - How do I check the status of one uploaded file?
      - Can I see the metadata for a single file by its ID?
      instructions:
      - text: Get file {id}.
        slots:
          id: path.id
      - text: Show the upload status and details of file {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/files/{id}/url'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a temporary download link for a file
      effect: read
      questions:
      - How do I download a file I uploaded?
      - Why can't I get a download link for a file that hasn't finished uploading?
      instructions:
      - text: Give me a download link for file {id}.
        slots:
          id: path.id
      - text: Generate a temporary URL to download file {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/files/{id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a pending file upload
      effect: destructive
      questions:
      - How do I abort an upload that hasn't been completed yet?
      - Can I cancel a file once it's already finished uploading?
      instructions:
      - text: Cancel the pending upload for file {id}.
        slots:
          id: path.id
      - text: Abort file upload {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'