# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Showpad Assets API
  version: 1.0.0
extends: openapi/showpad-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: 26
- target: $.paths['/assets.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List assets (legacy endpoint)
      effect: read
      questions:
      - Can I still list assets with the older .json assets endpoint?
      - How do I filter the legacy asset list to only shareable or sensitive files?
      instructions:
      - text: Using the legacy assets.json endpoint, list assets of file type {filetype}.
        slots:
          filetype: query.filetype
      - text: With the older list endpoint, find assets whose original file name is {originalName}.
        slots:
          originalName: query.originalName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload an asset (legacy endpoint)
      effect: write
      questions:
      - Is the old .json create-asset endpoint still usable for uploading a file?
      - Can I set an expiry date when creating an asset the legacy way?
      instructions:
      - text: Using the legacy create endpoint, upload {file} as an asset named {name}.
        slots:
          file: requestBody.file
          name: requestBody.name
      - text: Via assets.json, create asset {name} that expires at {expiresAt}.
        slots:
          name: requestBody.name
          expiresAt: requestBody.expiresAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/count.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Count assets
      effect: read
      questions:
      - How many assets are in our library?
      - What's the count of downloadable assets right now?
      instructions:
      - text: Count all assets.
      - text: Count the assets with file type {filetype}.
        slots:
          filetype: query.filetype
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/description.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Describe the asset data model
      effect: read
      questions:
      - What properties does the asset model have in the legacy API?
      - Where can I see which asset calls and parameters are allowed?
      instructions:
      - text: Describe the asset model and its available API calls.
      - text: Show me the field definitions for the asset resource.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id1}/tags/{id2}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Link or unlink an asset and tag via GET
      effect: write
      questions:
      - Is there a GET-based override to tag or untag an asset for clients that can't send POST?
      - Can I change an asset's tag assignment from the asset side with the method parameter?
      instructions:
      - text: From asset {id1}, use method {method} to change its link to tag {id2}.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      - text: Through GET on the asset path, apply {method} to asset {id1} and tag {id2}.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id1}/tags/{id2}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag an asset (from the asset side)
      effect: write
      questions:
      - How do I attach an existing tag to an asset using the asset's tag link endpoint?
      - Can I tag one asset by giving the asset ID first and then the tag ID?
      instructions:
      - text: On asset {id1}, link tag {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Apply existing tag {id2} to asset {id1} via the asset tag link.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id1}/tags/{id2}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Untag an asset (from the asset side)
      effect: write
      questions:
      - How do I remove a tag from an asset through the asset's unlink endpoint?
      - Can I untag an asset without deleting the tag itself?
      instructions:
      - text: On asset {id1}, unlink tag {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Strip tag {id2} off asset {id1} via the asset tag unlink.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an asset (legacy endpoint)
      effect: read
      questions:
      - Can I fetch one asset through the older .json endpoint?
      - What does the legacy single-asset response include?
      instructions:
      - text: Using the legacy endpoint, get asset {id}.
        slots:
          id: path.id
      - text: Fetch asset {id} from assets/{id}.json.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id}.json'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an asset (legacy PUT)
      effect: write
      questions:
      - How do I edit an asset's details with a PUT on the legacy endpoint?
      - Can I make an asset non-downloadable with a legacy PUT update?
      instructions:
      - text: PUT a legacy update renaming asset {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: With legacy PUT, set downloadable to {isDownloadable} on asset {id}.
        slots:
          id: path.id
          isDownloadable: requestBody.isDownloadable
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id}.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an asset (legacy POST .json)
      effect: write
      questions:
      - Is there a POST variant on the legacy .json path for editing an asset?
      - Can I mark an asset sensitive through the old POST update endpoint?
      instructions:
      - text: Via legacy POST to assets/{id}.json, set sensitive to {isSensitive}.
        slots:
          id: path.id
          isSensitive: requestBody.isSensitive
      - text: Using the old POST .json update, change asset {id}'s description to {description}.
        slots:
          id: path.id
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id}.json'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an asset (legacy endpoint)
      effect: destructive
      questions:
      - Can I still delete an asset using the legacy .json endpoint?
      - What's the older way to remove an asset by its ID?
      instructions:
      - text: Using the legacy endpoint, delete asset {id}.
        slots:
          id: path.id
      - text: Remove asset {id} via assets/{id}.json.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id}/comments.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on an asset
      effect: read
      questions:
      - What comments have people left on a particular asset?
      - Can I see only the comments on an asset created after a certain date?
      instructions:
      - text: List the comments on asset {id}.
        slots:
          id: path.id
      - text: Show comments on asset {id} created since {createdSince}.
        slots:
          id: path.id
          createdSince: query.createdSince
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id}/comments.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on an asset
      effect: write
      questions:
      - How do I add a comment to a specific asset?
      - Can an unregistered visitor's comment be recorded against an asset?
      instructions:
      - text: Comment {message} on asset {id}.
        slots:
          id: path.id
          message: requestBody.message
      - text: Post the comment {message} on asset {id} for unregistered user {unregisteredUserFirstName}.
        slots:
          id: path.id
          message: requestBody.message
          unregisteredUserFirstName: requestBody.unregisteredUserFirstName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Link related resources to an asset
      effect: write
      questions:
      - How do I attach several related resources to one asset with a Link list?
      - Can I connect an asset to other resources in bulk?
      instructions:
      - text: Link the resources {Link} to asset {id}.
        slots:
          id: path.id
          Link: requestBody.Link
      - text: Attach {Link} to asset {id} as related resources.
        slots:
          id: path.id
          Link: requestBody.Link
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id}/tags.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List an asset's tags
      effect: read
      questions:
      - Which tags are on a given asset?
      - Can I check whether an asset carries a tag with a specific name?
      instructions:
      - text: List the tags on asset {id}.
        slots:
          id: path.id
      - text: Check if asset {id} has a tag named {name}.
        slots:
          id: path.id
          name: query.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id}/tags.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new tag on an asset
      effect: write
      questions:
      - How do I create a brand-new tag and apply it to an asset in one call?
      - Can I set the division of a tag I'm creating on an asset?
      instructions:
      - text: Create tag {name} and add it to asset {id}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Add a new tag {name} in division {divisionId} to asset {id}.
        slots:
          id: path.id
          name: requestBody.name
          divisionId: requestBody.divisionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{id}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink related resources from an asset
      effect: write
      questions:
      - How do I detach a list of related resources from an asset?
      - Can I remove several resource links from one asset at once?
      instructions:
      - text: Unlink the resources {Link} from asset {id}.
        slots:
          id: path.id
          Link: requestBody.Link
      - text: Detach {Link} from asset {id}.
        slots:
          id: path.id
          Link: requestBody.Link
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List assets
      effect: read
      questions:
      - How do I list the assets in our Showpad library filtered by tag or division?
      - Can I look up assets by their external IDs or slugs?
      - Which assets carry a given set of tags?
      instructions:
      - text: List assets in divisions {divisionIds}.
        slots:
          divisionIds: query.divisionIds
      - text: List assets tagged {tagIds}.
        slots:
          tagIds: query.tagIds
      - text: Find assets with external IDs {externalIds}.
        slots:
          externalIds: query.externalIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an asset record
      effect: write
      questions:
      - How do I create a new asset record in a division?
      - Can I set languages, countries and authors when creating an asset?
      instructions:
      - text: Create an asset named {name} in division {division}.
        slots:
          name: requestBody.name
          division: requestBody.division
      - text: Create asset {name} in division {division} with tags {tags}.
        slots:
          name: requestBody.name
          division: requestBody.division
          tags: requestBody.tags
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/query'].post
  update:
    x-apievangelist-phrasing:
      intent: Search assets with ShowQL
      effect: read
      questions:
      - Can I filter assets with complex conditions on metadata, languages and countries?
      - How do I page through a large ShowQL result set with a cursor?
      instructions:
      - text: Query assets with the ShowQL expression {query}.
        slots:
          query: requestBody.query
      - text: Get the next page of ShowQL results for {query} using cursor {cursor}.
        slots:
          query: requestBody.query
          cursor: requestBody.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an asset
      effect: read
      questions:
      - How do I retrieve one asset's metadata by its ID?
      - What details come back for a single asset?
      instructions:
      - text: Get asset {assetId}.
        slots:
          assetId: path.assetId
      - text: Show the metadata of asset {assetId}.
        slots:
          assetId: path.assetId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an asset
      effect: write
      questions:
      - How do I archive an asset or change its permissions?
      - Can I update an asset's languages and localization?
      instructions:
      - text: Archive asset {assetId} by setting archived to {isArchived}.
        slots:
          assetId: path.assetId
          isArchived: requestBody.isArchived
      - text: Set the tags of asset {assetId} to {tags}.
        slots:
          assetId: path.assetId
          tags: requestBody.tags
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete an asset
      effect: destructive
      questions:
      - How do I permanently delete an asset from our library?
      - Can a deleted asset be recovered afterwards?
      instructions:
      - text: Permanently delete asset {assetId}.
        slots:
          assetId: path.assetId
      - text: Remove asset {assetId} from the Showpad library for good.
        slots:
          assetId: path.assetId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetId}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List an asset's file versions
      effect: read
      questions:
      - Which file versions are attached to an asset?
      - Can I see the original and processed files for one asset?
      instructions:
      - text: List the files of asset {assetId}.
        slots:
          assetId: path.assetId
      - text: Show all file versions belonging to asset {assetId}.
        slots:
          assetId: path.assetId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetId}/files'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a new file to an asset
      effect: write
      questions:
      - How do I upload a new file version to an existing asset?
      - Can I send an MD5 checksum when adding a file to an asset?
      instructions:
      - text: Attach a new file to asset {assetId}.
        slots:
          assetId: path.assetId
      - text: Add file {name} with checksum {contentMD5} to asset {assetId}.
        slots:
          assetId: path.assetId
          name: requestBody.name
          contentMD5: requestBody.contentMD5
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetId}/files/{fileId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an asset file's metadata
      effect: read
      questions:
      - How do I see the metadata of one specific file on an asset?
      - Does fetching a single asset file return the binary content?
      instructions:
      - text: Get file {fileId} of asset {assetId}.
        slots:
          assetId: path.assetId
          fileId: path.fileId
      - text: Show metadata for file {fileId} on asset {assetId}.
        slots:
          assetId: path.assetId
          fileId: path.fileId
      method: generated
      generated: '2026-10-01'