# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Flora.ai Assets API
  version: 1.0.0
extends: openapi/flora-fauna-assets-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: 5
- target: $.paths['/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List assets in a workspace or project
      effect: read
      questions:
      - How can I see all the media assets my Flora API key has access to?
      - Can I search my uploaded assets by name within one workspace?
      - Which assets belong to a specific project canvas?
      instructions:
      - text: List my assets.
      - text: Search assets for {query} in workspace {workspace_id}.
        slots:
          query: query.query
          workspace_id: query.workspace_id
      - text: Show the first {limit} assets in project {project_id}.
        slots:
          limit: query.limit
          project_id: query.project_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a new asset
      effect: write
      questions:
      - How do I import an image from a URL into my workspace as an asset?
      - Can I get a signed upload URL to push a local file as a new asset?
      - Is it possible to choose the folder a newly uploaded asset lands in?
      instructions:
      - text: Create an asset in workspace {workspace_id} from {source}.
        slots:
          workspace_id: requestBody.workspace_id
          source: requestBody.source
      - text: Upload {file_name} to folder {folder} in workspace {workspace_id} using source {source}.
        slots:
          file_name: requestBody.file_name
          folder: requestBody.folder
          workspace_id: requestBody.workspace_id
          source: requestBody.source
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one asset's metadata
      effect: read
      questions:
      - What metadata can I look up for a single asset by its ID?
      - Why would fetching an asset return 404 even though I know its ID?
      instructions:
      - text: Get the details of asset {assetId}.
        slots:
          assetId: path.assetId
      - text: Check whether asset {assetId} is accessible to my key.
        slots:
          assetId: path.assetId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetId}/complete'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a signed upload as complete
      effect: write
      questions:
      - What do I call after I finish pushing the file to the signed upload URL?
      - How does the asset get finalized once my signed-URL upload is done?
      instructions:
      - text: Mark the signed upload for asset {assetId} as complete.
        slots:
          assetId: path.assetId
      - text: Finalize asset {assetId} now that the file is uploaded.
        slots:
          assetId: path.assetId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetId}/retry'].post
  update:
    x-apievangelist-phrasing:
      intent: Retry a failed or expired asset upload
      effect: write
      questions:
      - My signed upload URL expired before the file finished — can I get a fresh one?
      - What happens if an asset upload fails, can it be retried without creating a new asset?
      instructions:
      - text: Get a new signed upload URL for asset {assetId}.
        slots:
          assetId: path.assetId
      - text: Retry the failed upload for asset {assetId}.
        slots:
          assetId: path.assetId
      method: generated
      generated: '2026-10-01'