# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely CMP Open API Documentation Library API
  version: 1.0.0
extends: openapi/optimizely-library-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 41
- target: $.paths['/folders'].get
  update:
    x-apievangelist-phrasing:
      intent: List library folders
      effect: read
      questions:
      - How do I see all the folders in my content marketing library?
      - Can I list only the subfolders inside one parent folder?
      - Which library folders were changed most recently?
      instructions:
      - text: List the folders in my library, newest changes first.
      - text: Show the subfolders inside folder {parent_folder_id}.
        slots:
          parent_folder_id: query.parent_folder_id
      - text: Get {page_size} library folders per page starting at offset {offset}.
        slots:
          page_size: query.page_size
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a library folder
      effect: write
      questions:
      - How do I make a new folder in the Optimizely content library?
      - Can I create a folder nested inside another folder?
      instructions:
      - text: Create a library folder named {name}.
        slots:
          name: requestBody.name
      - text: Create a folder called {name} inside parent folder {parent_folder_id}.
        slots:
          name: requestBody.name
          parent_folder_id: requestBody.parent_folder_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folders/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a library folder
      effect: read
      questions:
      - What are the details of a single library folder by its ID?
      - Can I look up one folder to see its name and parent?
      instructions:
      - text: Fetch library folder {id}.
        slots:
          id: path.id
      - text: Show me the details of folder {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folders/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a library folder
      effect: destructive
      questions:
      - How do I remove a folder from my library?
      - Is deleting a library folder still an experimental feature?
      instructions:
      - text: Delete library folder {id}.
        slots:
          id: path.id
      - text: Remove the folder {id} from the library.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folders/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or move a library folder
      effect: write
      questions:
      - How do I rename an existing library folder?
      - Can I move a folder under a different parent or back to the top level?
      instructions:
      - text: Rename folder {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Move folder {id} under parent folder {parent_folder_id}.
        slots:
          id: path.id
          parent_folder_id: requestBody.parent_folder_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folders/{id}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List who can access a folder
      effect: read
      questions:
      - Who has access to a particular library folder?
      - Can I filter a folder's permissions by access level?
      instructions:
      - text: List the users and teams with access to folder {id}.
        slots:
          id: path.id
      - text: Show accessors on folder {id} with at least {min_access} access.
        slots:
          id: path.id
          min_access: query.min_access
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folders/{id}/permissions'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant folder access to users or teams
      effect: write
      questions:
      - How do I share a library folder with a team?
      - Can I give specific users permission to a folder?
      instructions:
      - text: Grant {type} accessors {permissions} on folder {id}.
        slots:
          type: requestBody.type
          permissions: requestBody.permissions
          id: path.id
      - text: 'Share folder {id} with these accessors: {permissions}.'
        slots:
          id: path.id
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folders/{id}/permissions/{accessor_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke someone's access to a folder
      effect: destructive
      questions:
      - How do I take away a user's access to a library folder?
      - Can I remove a team from a folder's permissions?
      instructions:
      - text: Remove accessor {accessor_id} from folder {id}.
        slots:
          accessor_id: path.accessor_id
          id: path.id
      - text: Revoke folder {id} access for {accessor_id}.
        slots:
          id: path.id
          accessor_id: path.accessor_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folders/{id}/permissions/{accessor_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change someone's access level on a folder
      effect: write
      questions:
      - How do I change a user's access level on a library folder?
      - Can I make someone an owner of a folder?
      instructions:
      - text: Set accessor {accessor_id}'s access on folder {id} to {access_type}.
        slots:
          accessor_id: path.accessor_id
          id: path.id
          access_type: requestBody.access_type
      - text: Make {accessor_id} an owner of folder {id}.
        slots:
          accessor_id: path.accessor_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/file-urls'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate download URLs for library files
      effect: write
      questions:
      - How do I get download links for files stored in my library?
      - Can I generate download URLs for several files at once by their GUIDs?
      instructions:
      - text: Generate download URLs for file GUIDs {guids}.
        slots:
          guids: requestBody.guids
      - text: Give me download links for the library files {guids}.
        slots:
          guids: requestBody.guids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List and search library assets
      effect: read
      questions:
      - How do I list the images and videos in my content library?
      - Can I search library assets by title or description text?
      - Which assets were modified within a given date range?
      - Can I list only the assets that belong to one campaign?
      instructions:
      - text: List library assets of type {type}.
        slots:
          type: query.type
      - text: Search the library for assets matching {search_text}.
        slots:
          search_text: query.search_text
      - text: Show assets in folder {folder_id}, including subfolders.
        slots:
          folder_id: query.folder_id
      - text: List the assets for campaign {campaign_id}.
        slots:
          campaign_id: query.campaign_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a new library asset
      effect: write
      questions:
      - How do I add a new image, video or raw file to the library?
      - Can I put a newly uploaded asset straight into a specific folder?
      instructions:
      - text: Create an asset titled {title} from upload session {key}.
        slots:
          title: requestBody.title
          key: requestBody.key
      - text: Add uploaded file {key} as asset {title} in folder {folder_id}.
        slots:
          key: requestBody.key
          title: requestBody.title
          folder_id: requestBody.folder_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List an asset's custom fields
      effect: read
      questions:
      - What custom field values are set on a library asset?
      - Can I page through the fields attached to one asset?
      instructions:
      - text: List the fields on asset {asset_id}.
        slots:
          asset_id: path.asset_id
      - text: Show the custom field values for asset {asset_id}.
        slots:
          asset_id: path.asset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/fields'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all fields on an asset
      effect: write
      questions:
      - How do I overwrite every custom field on an asset in one call?
      - Can I replace an asset's whole set of field values?
      instructions:
      - text: Replace all field values on asset {asset_id}.
        slots:
          asset_id: path.asset_id
      - text: Overwrite the complete field set of asset {asset_id}.
        slots:
          asset_id: path.asset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/fields/{field_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one field value on an asset
      effect: write
      questions:
      - How do I change a single custom field value on an asset?
      - Can I edit one field without touching an asset's other fields?
      instructions:
      - text: Update field {field_id} on asset {asset_id}.
        slots:
          field_id: path.field_id
          asset_id: path.asset_id
      - text: Set a new value for field {field_id} of asset {asset_id}.
        slots:
          field_id: path.field_id
          asset_id: path.asset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new version to an asset
      effect: write
      questions:
      - How do I upload a new version of an existing image or video?
      - Can I keep version history when replacing a library file?
      instructions:
      - text: Add a new version of asset {asset_id} from upload {key} titled {title}.
        slots:
          asset_id: path.asset_id
          key: requestBody.key
          title: requestBody.title
      - text: Upload upload-session {key} as the latest version of asset {asset_id}, titled {title}.
        slots:
          key: requestBody.key
          asset_id: path.asset_id
          title: requestBody.title
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/renditions'].get
  update:
    x-apievangelist-phrasing:
      intent: List an asset's renditions
      effect: read
      questions:
      - What renditions or resized versions exist for an asset?
      - Can I see every rendition generated for one image?
      instructions:
      - text: List the renditions of asset {asset_id}.
        slots:
          asset_id: path.asset_id
      - text: Show all renditions generated for asset {asset_id}.
        slots:
          asset_id: path.asset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List who can access an asset
      effect: read
      questions:
      - Who has permission to access a particular library asset?
      - Can I filter an asset's accessors by maximum access level?
      instructions:
      - text: List the users and teams with access to asset {asset_id}.
        slots:
          asset_id: path.asset_id
      - text: Show accessors on asset {asset_id} with {access} access.
        slots:
          asset_id: path.asset_id
          access: query.access
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/permissions'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant asset access to users or teams
      effect: write
      questions:
      - How do I share a single library asset with a team?
      - Can I give specific users permission to one asset?
      instructions:
      - text: Grant {type} accessors {permissions} on asset {asset_id}.
        slots:
          type: requestBody.type
          permissions: requestBody.permissions
          asset_id: path.asset_id
      - text: 'Share asset {asset_id} with these accessors: {permissions}.'
        slots:
          asset_id: path.asset_id
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/permissions/{accessor_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke someone's access to an asset
      effect: destructive
      questions:
      - How do I take away a user's access to a library asset?
      - Can I remove a team from an asset's permissions?
      instructions:
      - text: Remove accessor {accessor_id} from asset {asset_id}.
        slots:
          accessor_id: path.accessor_id
          asset_id: path.asset_id
      - text: Revoke asset {asset_id} access for {accessor_id}.
        slots:
          asset_id: path.asset_id
          accessor_id: path.accessor_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/permissions/{accessor_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change someone's access level on an asset
      effect: write
      questions:
      - How do I change a user's access level on a single asset?
      - Can I make someone an owner of an asset?
      instructions:
      - text: Set accessor {accessor_id}'s access on asset {asset_id} to {access_type}.
        slots:
          accessor_id: path.accessor_id
          asset_id: path.asset_id
          access_type: requestBody.access_type
      - text: Make {accessor_id} an owner of asset {asset_id}.
        slots:
          accessor_id: path.accessor_id
          asset_id: path.asset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/renditions/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a rendition
      effect: read
      questions:
      - What are the details of one rendition by its ID?
      - Can I look up a single rendition directly without its asset?
      instructions:
      - text: Fetch rendition {id}.
        slots:
          id: path.id
      - text: Show me the details of rendition {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rendition-configs/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a rendition configuration
      effect: read
      questions:
      - How is a rendition configuration for my organization set up?
      - Can I inspect the settings of one rendition config by ID?
      instructions:
      - text: Get rendition configuration {id}.
        slots:
          id: path.id
      - text: Show the rendition config settings for {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/lineages'].post
  update:
    x-apievangelist-phrasing:
      intent: Record where an asset is used externally
      effect: write
      questions:
      - How do I track that an asset is used on an external website?
      - Can I record which rendition of an asset a page is using?
      instructions:
      - text: Record that asset {asset_id} is used at {uri} by source {name}.
        slots:
          asset_id: path.asset_id
          uri: requestBody.uri
          name: requestBody.name
      - text: Add a lineage for asset {asset_id} pointing to {uri}, named {name}, using rendition {rendition_id}.
        slots:
          asset_id: path.asset_id
          uri: requestBody.uri
          name: requestBody.name
          rendition_id: requestBody.rendition_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/lineages/{lineage_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an asset lineage record
      effect: destructive
      questions:
      - How do I remove an external usage record from an asset?
      - Can I delete a lineage entry once an asset is no longer used there?
      instructions:
      - text: Delete lineage {lineage_id} from asset {asset_id}.
        slots:
          lineage_id: path.lineage_id
          asset_id: path.asset_id
      - text: Remove the usage record {lineage_id} on asset {asset_id}.
        slots:
          lineage_id: path.lineage_id
          asset_id: path.asset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/related-assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List an asset's related assets
      effect: read
      questions:
      - Which assets are linked as related to a given article or image?
      - What asset types support related assets?
      instructions:
      - text: List the related assets of asset {asset_id}.
        slots:
          asset_id: path.asset_id
      - text: Show assets linked as related to {asset_id}.
        slots:
          asset_id: path.asset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{asset_id}/related-assets'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an asset's related assets
      effect: write
      questions:
      - How do I set the full list of related assets for an asset?
      - Can I overwrite which assets are linked as related to a video?
      instructions:
      - text: Replace the related assets of {asset_id} with {related_assets}.
        slots:
          asset_id: path.asset_id
          related_assets: requestBody.related_assets
      - text: Set {related_assets} as the only related assets on asset {asset_id}.
        slots:
          related_assets: requestBody.related_assets
          asset_id: path.asset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asset-lineages'].get
  update:
    x-apievangelist-phrasing:
      intent: List asset lineage records
      effect: read
      questions:
      - Where are my library assets being used across external sites?
      - Can I filter lineage records by where an asset is used?
      instructions:
      - text: List all asset lineage records.
      - text: Show lineage records for asset {asset_id}.
        slots:
          asset_id: query.asset_id
      - text: Find lineages where assets are used in {used_in}.
        slots:
          used_in: query.used_in
      method: generated
      generated: '2026-09-26'
- target: $.paths['/articles/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an article
      effect: read
      questions:
      - How do I fetch a single article from the library?
      - Can I read an article's content by its ID?
      instructions:
      - text: Get article {id}.
        slots:
          id: path.id
      - text: Show me the library article {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/images/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an image
      effect: read
      questions:
      - How do I fetch the details of a library image?
      - Can I see an image's alt text and tags by its ID?
      instructions:
      - text: Get image {id}.
        slots:
          id: path.id
      - text: Show me the library image {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/images/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an image
      effect: destructive
      questions:
      - How do I delete an image from my content library?
      - Is deleting a library image permanent rather than archiving it?
      instructions:
      - text: Delete image {id}.
        slots:
          id: path.id
      - text: Remove the library image {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/images/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an image's metadata
      effect: write
      questions:
      - How do I change an image's title or alt text?
      - Can I make a library image public or set it to expire?
      - Can I archive an image or stop search engines indexing it?
      instructions:
      - text: Set the alt text of image {id} to {alt_text}.
        slots:
          id: path.id
          alt_text: requestBody.alt_text
      - text: Rename image {id} to {title}.
        slots:
          id: path.id
          title: requestBody.title
      - text: Make image {id} expire at {expires_at}.
        slots:
          id: path.id
          expires_at: requestBody.expires_at
      method: generated
      generated: '2026-09-26'
- target: $.paths['/videos/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a video
      effect: read
      questions:
      - How do I fetch the details of a library video?
      - Can I see a video's description and tags by its ID?
      instructions:
      - text: Get video {id}.
        slots:
          id: path.id
      - text: Show me the library video {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/videos/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a video
      effect: destructive
      questions:
      - How do I delete a video from my content library?
      - Can I permanently remove a video asset by ID?
      instructions:
      - text: Delete video {id}.
        slots:
          id: path.id
      - text: Remove the library video {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/videos/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a video's metadata
      effect: write
      questions:
      - How do I change a video's title or description?
      - Can I move a video into another folder or archive it?
      instructions:
      - text: Set the description of video {id} to {description}.
        slots:
          id: path.id
          description: requestBody.description
      - text: Move video {id} into folder {folder_id}.
        slots:
          id: path.id
          folder_id: requestBody.folder_id
      - text: Replace the tags on video {id} with {tags}.
        slots:
          id: path.id
          tags: requestBody.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/raw-files/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a raw file
      effect: read
      questions:
      - How do I fetch the details of a raw file in the library?
      - Can I look up a PDF or other raw file asset by ID?
      instructions:
      - text: Get raw file {id}.
        slots:
          id: path.id
      - text: Show me the library raw file {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/raw-files/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a raw file
      effect: destructive
      questions:
      - How do I delete a raw file from my content library?
      - Can I permanently remove a raw file asset by ID?
      instructions:
      - text: Delete raw file {id}.
        slots:
          id: path.id
      - text: Remove the library raw file {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/raw-files/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a raw file's metadata
      effect: write
      questions:
      - How do I rename a raw file or change its attribution text?
      - Can I make a raw file's URL public?
      instructions:
      - text: Rename raw file {id} to {title}.
        slots:
          id: path.id
          title: requestBody.title
      - text: Set the attribution text of raw file {id} to {attribution_text}.
        slots:
          id: path.id
          attribution_text: requestBody.attribution_text
      - text: Archive raw file {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-contents'].post
  update:
    x-apievangelist-phrasing:
      intent: Create structured content
      effect: write
      questions:
      - How do I create a structured content asset in the library?
      - Can I put new structured content into a specific folder?
      instructions:
      - text: Create structured content titled {title} with body {content_body}.
        slots:
          title: requestBody.title
          content_body: requestBody.content_body
      - text: Add structured content {content_body} to folder {folder_id}.
        slots:
          content_body: requestBody.content_body
          folder_id: requestBody.folder_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-contents/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get structured content
      effect: read
      questions:
      - How do I read a structured content asset by ID?
      - Can I fetch the body of one structured content item?
      instructions:
      - text: Get structured content {id}.
        slots:
          id: path.id
      - text: Show me the structured content body for {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-contents/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update structured content
      effect: write
      questions:
      - How do I edit the body of a structured content asset?
      - Can I archive a structured content item?
      instructions:
      - text: Update the body of structured content {id} to {content_body}.
        slots:
          id: path.id
          content_body: requestBody.content_body
      - text: Archive structured content {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'