# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Khoros Ai Conversations API
  version: 1.0.0
extends: openapi/khoros-ai-conversations-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 39
- target: $.paths['/{lswUuid}/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List a Care author's conversation IDs for a day
      effect: read
      questions:
      - Which conversations did a specific Care author have during one 24-hour window?
      - How do I get the conversation IDs tied to one customer author in Khoros Care?
      - Can I limit an author's conversation ID lookup to a start and end time in epoch milliseconds?
      instructions:
      - text: Get the conversation IDs for Care author {author} between {start} and {end}.
        slots:
          author: path.lswUuid
          start: query.startEpochMillis
          end: query.endEpochMillis
      - text: List today's conversation IDs for Care author {author}.
        slots:
          author: path.lswUuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiative-id}/accountset'].get
  update:
    x-apievangelist-phrasing:
      intent: List account sets and accounts for an initiative
      effect: read
      questions:
      - Which account sets and social accounts can I post to inside a marketing initiative?
      - What accounts are grouped under each account set for my initiative?
      instructions:
      - text: Show every account set and its accounts in initiative {initiative}.
        slots:
          initiative: path.initiative-id
      - text: List the publishing accounts available to me in initiative {initiative}.
        slots:
          initiative: path.initiative-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/asset'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a text asset in the Content Center
      effect: write
      questions:
      - How do I add a reusable text snippet to the Khoros Marketing Content Center?
      - Can a text asset be limited to certain social networks and an availability window?
      - Which folder does a new text asset have to go into?
      instructions:
      - text: Create a text asset named {name} in folder {folder} with the text {text}.
        slots:
          name: requestBody.name
          folder: requestBody.folderId
          text: requestBody.text
      - text: Add a text asset to folder {folder} that is available from {start} until {end}.
        slots:
          folder: requestBody.folderId
          start: requestBody.startDate
          end: requestBody.endDate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/asset?multipart'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload an image or video asset to the Content Center
      effect: write
      questions:
      - Can I upload an image or video file as a Content Center asset?
      - What do I need to upload a video asset for publishing and moderation?
      instructions:
      - text: Upload an image asset named {name} into Content Center folder {folder}.
        slots:
          name: requestBody.name
          folder: requestBody.folderId
      - text: Upload a video file as a Content Center asset in folder {folder} and mark it for publishing.
        slots:
          folder: requestBody.folderId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/asset/{assetId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Content Center asset by ID
      effect: read
      questions:
      - How can I see the details and content labels of one Content Center asset?
      - What does a single asset record show, including its labels?
      instructions:
      - text: Get Content Center asset {asset} with its content labels.
        slots:
          asset: path.assetId
      - text: Show me the details of asset {asset}.
        slots:
          asset: path.assetId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/asset/{assetId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing Content Center asset
      effect: write
      questions:
      - Can I rename or move an existing Content Center asset to another folder?
      - Is it possible to strip the image or video off an asset I already created?
      instructions:
      - text: Rename Content Center asset {asset} to {name}.
        slots:
          asset: path.assetId
          name: requestBody.name
      - text: Move asset {asset} into folder {folder}.
        slots:
          asset: path.assetId
          folder: requestBody.folderId
      - text: Remove the video from asset {asset}.
        slots:
          asset: path.assetId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/folder'].get
  update:
    x-apievangelist-phrasing:
      intent: List Content Center folders
      effect: read
      questions:
      - What asset folders exist in our Khoros Marketing Content Center?
      - Can I filter the Content Center folder list by name?
      instructions:
      - text: List all Content Center folders.
      - text: Find Content Center folders whose name matches {name}.
        slots:
          name: query.nameFilter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/folder'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Content Center asset folder
      effect: write
      questions:
      - How do I make a new custom folder to organize marketing assets?
      - Can I give a new asset folder a description?
      instructions:
      - text: Create an asset folder called {name}.
        slots:
          name: requestBody.name
      - text: Make a new Content Center folder {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/folder/{folderId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Content Center folder by ID
      effect: read
      questions:
      - How do I look up one asset folder's name and description by its ID?
      - What details come back for a single Content Center folder?
      instructions:
      - text: Get asset folder {folder}.
        slots:
          folder: path.folderId
      - text: Show the name and description of Content Center folder {folder}.
        slots:
          folder: path.folderId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/folder/{folderId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or describe a Content Center folder
      effect: write
      questions:
      - Can I rename an existing Content Center folder?
      - How do I change the description on an asset folder I already have?
      instructions:
      - text: Rename asset folder {folder} to {name}.
        slots:
          folder: path.folderId
          name: requestBody.name
      - text: Update the description of Content Center folder {folder} to {description}.
        slots:
          folder: path.folderId
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/folder/{folderId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Content Center folder
      effect: destructive
      questions:
      - Can I delete an asset folder from the Content Center?
      - How do I get rid of a Content Center folder we no longer use?
      instructions:
      - text: Delete asset folder {folder}.
        slots:
          folder: path.folderId
      - text: Remove Content Center folder {folder} permanently.
        slots:
          folder: path.folderId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/folder/{folderId}/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List the assets inside a folder
      effect: read
      questions:
      - Which assets are stored in a particular Content Center folder?
      - Can I sort the assets in a folder ascending or descending?
      instructions:
      - text: List the assets in folder {folder}.
        slots:
          folder: path.folderId
      - text: Show assets in folder {folder} ordered by {order} {direction}.
        slots:
          folder: path.folderId
          order: query.orderBy
          direction: query.direction
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/calendar/customChannel'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom calendar channels
      effect: read
      questions:
      - What custom channels are set up on our marketing calendar?
      - Do we have any CustomChannels defined for non-social publishing?
      instructions:
      - text: List all CustomChannels.
      - text: Show every custom channel on the marketing calendar.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/calendar/customChannel'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom calendar channel
      effect: write
      questions:
      - How do I add a custom channel, like a newsletter, to the Khoros marketing calendar?
      - Can a new CustomChannel have a contact name and an image?
      instructions:
      - text: Create a CustomChannel named {name} of type {type}.
        slots:
          name: requestBody.name
          type: requestBody.type
      - text: Add a custom channel {name} with contact {contact}.
        slots:
          name: requestBody.name
          contact: requestBody.contactName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/calendar/customChannel/{customChannelId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom calendar channel by ID
      effect: read
      questions:
      - How do I fetch one CustomChannel I created earlier?
      - What are the name, type and contact of a specific custom channel?
      instructions:
      - text: Get CustomChannel {channel}.
        slots:
          channel: path.customChannelId
      - text: Show the details of custom channel {channel}.
        slots:
          channel: path.customChannelId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/calendar/customChannel/{customChannelId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom calendar channel
      effect: write
      questions:
      - Can I rename a custom channel or change its contact person?
      - How do I swap the image on an existing CustomChannel?
      instructions:
      - text: Rename CustomChannel {channel} to {name}.
        slots:
          channel: path.customChannelId
          name: requestBody.name
      - text: Change the contact on custom channel {channel} to {contact}.
        slots:
          channel: path.customChannelId
          contact: requestBody.contactName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/calendar/customChannelItem/{customChannelItemId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom channel calendar item
      effect: read
      questions:
      - How do I look up one scheduled item on a custom channel?
      - What title, text and publish date does a CustomChannelItem hold?
      instructions:
      - text: Get CustomChannelItem {item} in initiative {initiative}.
        slots:
          item: path.customChannelItemId
          initiative: path.initiativeId
      - text: Show calendar item {item} from initiative {initiative}.
        slots:
          item: path.customChannelItemId
          initiative: path.initiativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/calendar/customChannelItem/{customChannelItemId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom channel calendar item
      effect: write
      questions:
      - Can I reschedule an existing custom channel item to a new publish date?
      - How do I edit the title or text of a CustomChannelItem already on the calendar?
      instructions:
      - text: Reschedule CustomChannelItem {item} in initiative {initiative} to {date}.
        slots:
          item: path.customChannelItemId
          initiative: path.initiativeId
          date: requestBody.scheduledPublishDate
      - text: Change the title of calendar item {item} in initiative {initiative} to {title}.
        slots:
          item: path.customChannelItemId
          initiative: path.initiativeId
          title: requestBody.title
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/calendar/customChannelItem/{customChannelItemId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an item to a custom channel calendar
      effect: write
      questions:
      - How do I put a new piece of content on a custom channel in the marketing calendar?
      - Can a new CustomChannelItem carry an image and a scheduled publish date?
      instructions:
      - text: Create CustomChannelItem {item} in initiative {initiative} titled {title}.
        slots:
          item: path.customChannelItemId
          initiative: path.initiativeId
          title: requestBody.title
      - text: Add a new custom channel item {item} to initiative {initiative} scheduled for {date}.
        slots:
          item: path.customChannelItemId
          initiative: path.initiativeId
          date: requestBody.scheduledPublishDate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/calendar/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List calendar messages posted or scheduled
      effect: read
      questions:
      - Which social messages are published or scheduled on our marketing calendar?
      - Can I filter calendar messages by initiative, plan and date range?
      - How many calendar messages come back per page, and what is the maximum?
      instructions:
      - text: List calendar messages published between {start} and {end}.
        slots:
          start: query.startDate
          end: query.endDate
      - text: Show scheduled and posted messages for plans {plans}.
        slots:
          plans: query.planIds
      - text: List calendar messages in initiatives {initiatives}, {per_page} per page.
        slots:
          initiatives: query.initiativeIds
          per_page: query.perPage
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative'].get
  update:
    x-apievangelist-phrasing:
      intent: List marketing initiatives
      effect: read
      questions:
      - What initiatives does our company have in Khoros Marketing?
      - Can I search initiatives by name?
      instructions:
      - text: List all initiatives for my company.
      - text: Find initiatives named like {name}.
        slots:
          name: query.nameFilter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one marketing initiative
      effect: read
      questions:
      - How do I see the details of a single initiative?
      - What information is stored on one marketing initiative?
      instructions:
      - text: Get initiative {initiative}.
        slots:
          initiative: path.initiativeId
      - text: Show me the details of marketing initiative {initiative}.
        slots:
          initiative: path.initiativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/contentLabel'].get
  update:
    x-apievangelist-phrasing:
      intent: List content labels in an initiative
      effect: read
      questions:
      - Which content labels can I tag messages with in an initiative?
      - Can I list only the top labels, or search labels by text?
      instructions:
      - text: List content labels in initiative {initiative}.
        slots:
          initiative: path.initiativeId
      - text: Search labels in initiative {initiative} matching {text}.
        slots:
          initiative: path.initiativeId
          text: query.q
      - text: Show only the top labels for initiative {initiative}.
        slots:
          initiative: path.initiativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/message'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish an image-set message to social
      effect: write
      questions:
      - How do I publish a post with a set of images through Khoros Marketing?
      - Can I schedule an image-set message for later instead of posting now?
      instructions:
      - text: Publish an image-set message titled {title} to {network} in initiative {initiative}.
        slots:
          title: requestBody.title
          network: requestBody.service
          initiative: path.initiativeId
      - text: Schedule an image-set post in initiative {initiative} for {date}.
        slots:
          initiative: path.initiativeId
          date: requestBody.scheduledPublishDate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/message/{messageId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a published or scheduled message
      effect: read
      questions:
      - How do I check the status and content of a message I published?
      - What publication results are stored on an existing marketing message?
      instructions:
      - text: Get message {message} in initiative {initiative}.
        slots:
          message: path.messageId
          initiative: path.initiativeId
      - text: Show the status of marketing message {message} from initiative {initiative}.
        slots:
          message: path.messageId
          initiative: path.initiativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/message/{messageId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit an existing social message
      effect: write
      questions:
      - Can I change the title or labels of a message after creating it?
      - How do I move a standard message to a different scheduled time?
      instructions:
      - text: Change the title of message {message} in initiative {initiative} to {title}.
        slots:
          message: path.messageId
          initiative: path.initiativeId
          title: requestBody.title
      - text: Reschedule message {message} in initiative {initiative} for {date}.
        slots:
          message: path.messageId
          initiative: path.initiativeId
          date: requestBody.scheduledPublishDate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/message/{messageId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a marketing message
      effect: destructive
      questions:
      - Can I delete a message I scheduled by mistake?
      - How do I remove a marketing message from an initiative?
      instructions:
      - text: Delete message {message} from initiative {initiative}.
        slots:
          message: path.messageId
          initiative: path.initiativeId
      - text: Remove scheduled message {message} in initiative {initiative}.
        slots:
          message: path.messageId
          initiative: path.initiativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/message?multipart'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a message with an uploaded file
      effect: write
      questions:
      - How do I publish a social post and upload its media in the same multipart request?
      - Can a multipart message be saved as a draft instead of published?
      instructions:
      - text: Publish a multipart message with an attached file to {network} in initiative {initiative}.
        slots:
          network: requestBody.service
          initiative: path.initiativeId
      - text: Create a multipart draft message titled {title} in initiative {initiative}.
        slots:
          title: requestBody.title
          initiative: path.initiativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/message/{messageId}?multipart'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a multipart message and its media
      effect: write
      questions:
      - Can I replace the uploaded file on a multipart message I already created?
      - How do I edit a multi-part message rather than a plain one?
      instructions:
      - text: Update multipart message {message} in initiative {initiative} with a new file.
        slots:
          message: path.messageId
          initiative: path.initiativeId
      - text: Retitle multi-part message {message} in initiative {initiative} to {title}.
        slots:
          message: path.messageId
          initiative: path.initiativeId
          title: requestBody.title
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/multiChannelMessage/{messageId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a multi-channel message
      effect: read
      questions:
      - How do I look up a message that was published across several channels at once?
      - What does a multi-channel message record contain?
      instructions:
      - text: Get multi-channel message {message} in initiative {initiative}.
        slots:
          message: path.messageId
          initiative: path.initiativeId
      - text: Show the cross-channel message {message} from initiative {initiative}.
        slots:
          message: path.messageId
          initiative: path.initiativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/privilege'].get
  update:
    x-apievangelist-phrasing:
      intent: List my permissions in the current company
      effect: read
      questions:
      - What am I allowed to do in the currently selected Khoros Marketing company?
      - Which privileges does my user have?
      instructions:
      - text: List my permissions in the current company.
      - text: Show the privileges granted to the current user.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/plan'].get
  update:
    x-apievangelist-phrasing:
      intent: List plans in an initiative
      effect: read
      questions:
      - Which campaign plans exist under one initiative?
      - Can I search an initiative's plans by name?
      instructions:
      - text: List the plans in initiative {initiative}.
        slots:
          initiative: path.initiativeId
      - text: Find plans in initiative {initiative} named like {name}.
        slots:
          initiative: path.initiativeId
          name: query.nameFilter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List user roles for the company
      effect: read
      questions:
      - What user roles are defined for our company?
      - Which role IDs can I assign when creating a user?
      instructions:
      - text: List the roles in my company.
      - text: Show page {page} of company roles.
        slots:
          page: query.pageNumber
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/users/initiative/{initiativeId}/publishers'].get
  update:
    x-apievangelist-phrasing:
      intent: List publishers for an initiative
      effect: read
      questions:
      - Who can publish messages in a given initiative?
      - Which users are publishers on one initiative?
      instructions:
      - text: List the publishers for initiative {initiative}.
        slots:
          initiative: path.initiativeId
      - text: Show who is allowed to publish in initiative {initiative}.
        slots:
          initiative: path.initiativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/user/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from the company
      effect: destructive
      questions:
      - How do I remove someone's user account from our Khoros Marketing company?
      - Can I delete a user who has left the team?
      instructions:
      - text: Delete user {user} from the company.
        slots:
          user: path.userId
      - text: Remove company user {user}.
        slots:
          user: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/user'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new user to the company
      effect: write
      questions:
      - How do I add a new teammate as a user with a role and workspace?
      - Can a new user be sent an invitation email with a custom message?
      - Is it possible to auto-add a new user to future initiatives and account sets?
      instructions:
      - text: Create user {email} named {first} {last} with role {role} in workspace {workspace}.
        slots:
          email: requestBody.email
          first: requestBody.firstName
          last: requestBody.lastName
          role: requestBody.roleId
          workspace: requestBody.workspaceId
      - text: Add {email} as a user and send them an invite with the message {message}.
        slots:
          email: requestBody.email
          message: requestBody.inviteMessage
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in the company
      effect: read
      questions:
      - Who are the users in our Khoros Marketing company?
      - Can I search users by first name, last name or email?
      instructions:
      - text: List all users in the company.
      - text: Find users matching {search}.
        slots:
          search: query.nameEmailFilter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/conversations/initiative/{initiativeId}/video/captions'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload captions for a video
      effect: write
      questions:
      - How do I attach SRT captions to a video post?
      - What file naming does a video captions upload require?
      instructions:
      - text: Upload the SRT captions file {file} for a video in initiative {initiativeId}.
        slots:
          file: requestBody.captions
          initiativeId: path.initiativeId
      - text: Create a video captions object from {file} under initiative {initiativeId}.
        slots:
          file: requestBody.captions
          initiativeId: path.initiativeId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/conversations/workspaces'].get
  update:
    x-apievangelist-phrasing:
      intent: List workspaces for the company
      effect: read
      questions:
      - What workspaces does our company have?
      - Which workspace IDs can I put a new user in?
      instructions:
      - text: List the workspaces in my company.
      - text: Show page {page} of company workspaces.
        slots:
          page: query.pageNumber
      method: generated
      generated: '2026-10-01'