# 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 Networks API
  version: 1.0.0
extends: openapi/khoros-ai-networks-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: 21
- target: $.paths['/networks/{networktype}/ids/{networkid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an author by social network ID
      effect: read
      questions:
      - How do I look up a Khoros Care author from their Facebook or Instagram user ID?
      - Can I include authors whose CRM data was deleted when looking one up by network ID?
      instructions:
      - text: Get the author with network ID {networkid} on {networktype}.
        slots:
          networktype: path.networktype
          networkid: path.networkid
      - text: Look up {networktype} author {networkid}, including deleted CRM data {include_deleted_crm}.
        slots:
          networktype: path.networktype
          networkid: path.networkid
          include_deleted_crm: query.include_deleted_crm
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/ids/{networkid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an author by social network ID
      effect: write
      questions:
      - Can I update an author record using their network ID on a single-instance network?
      - How do I edit an author found by their default-network ID?
      instructions:
      - text: Update the author with ID {networkid} on the default {networktype} instance.
        slots:
          networktype: path.networktype
          networkid: path.networkid
      - text: Save changes to {networktype} author {networkid}.
        slots:
          networktype: path.networktype
          networkid: path.networkid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/instances/{networkinstance}/ids/{networkid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an author by network ID on an instance
      effect: read
      questions:
      - How do I find an author by network ID when we have several instances of that network?
      - Can I look up an author on one specific network instance?
      instructions:
      - text: Get author {networkid} on {networktype} instance {networkinstance}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkid: path.networkid
      - text: Fetch the profile for ID {networkid} in instance {networkinstance} of {networktype}, with deleted CRM {include_deleted_crm}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkid: path.networkid
          include_deleted_crm: query.include_deleted_crm
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/instances/{networkinstance}/ids/{networkid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an author by network ID on an instance
      effect: write
      questions:
      - Can I update an author on a specific instance of a network?
      - How do I change author details when the network has multiple instances?
      instructions:
      - text: Update author {networkid} on {networktype} instance {networkinstance}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkid: path.networkid
      - text: Edit the record for user {networkid} in {networktype} instance {networkinstance}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkid: path.networkid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/handles/{networkhandle}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find authors by social handle
      effect: read
      questions:
      - How do I find an author by their social media handle?
      - Can one handle return more than one author?
      instructions:
      - text: Find authors with handle {networkhandle} on {networktype}.
        slots:
          networktype: path.networktype
          networkhandle: path.networkhandle
      - text: Who is @{networkhandle} on {networktype}? Pull their author record.
        slots:
          networktype: path.networktype
          networkhandle: path.networkhandle
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/instances/{networkinstance}/handles/{networkhandle}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find authors by handle on a network instance
      effect: read
      questions:
      - Can I search for an author handle within one specific network instance?
      - Which authors use a given handle on a particular instance of a network?
      instructions:
      - text: Find authors with handle {networkhandle} on {networktype} instance {networkinstance}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkhandle: path.networkhandle
      - text: Look up @{networkhandle} only within instance {networkinstance} of {networktype}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkhandle: path.networkhandle
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/ids/{networkid}/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List an author's conversation IDs by network ID
      effect: read
      questions:
      - Which conversations did an author have on a given day, looked up by network ID?
      - Is the conversation lookup by network ID limited to a 24-hour period?
      instructions:
      - text: List conversation IDs for {networktype} user ID {networkid} between {startEpochMillis} and {endEpochMillis}.
        slots:
          networktype: path.networktype
          networkid: path.networkid
          startEpochMillis: query.startEpochMillis
          endEpochMillis: query.endEpochMillis
      - text: Show today's conversations with {networktype} user {networkid}.
        slots:
          networktype: path.networktype
          networkid: path.networkid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/instances/{networkinstance}/ids/{networkid}/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List an author's conversation IDs per instance
      effect: read
      questions:
      - How do I get one day of an author's conversation IDs on a specific network instance by user ID?
      - Can I pull an author's daily conversations for one instance of a network?
      instructions:
      - text: List conversation IDs for user ID {networkid} on {networktype} instance {networkinstance} starting {startEpochMillis}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkid: path.networkid
          startEpochMillis: query.startEpochMillis
      - text: Show the conversations user {networkid} had that day on instance {networkinstance} of {networktype}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkid: path.networkid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/handles/{networkhandle}/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List an author's conversation IDs by handle
      effect: read
      questions:
      - Which conversations did a social handle have with us over a day?
      - Can I get conversation IDs for an author using only their handle?
      instructions:
      - text: List conversation IDs for handle {networkhandle} on {networktype} from {startEpochMillis}.
        slots:
          networktype: path.networktype
          networkhandle: path.networkhandle
          startEpochMillis: query.startEpochMillis
      - text: Show the day's conversations with @{networkhandle} on {networktype}.
        slots:
          networktype: path.networktype
          networkhandle: path.networkhandle
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/instances/{networkinstance}/handles/{networkhandle}/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List conversation IDs by handle on an instance
      effect: read
      questions:
      - How do I find a handle's conversations on one particular network instance?
      - Can I pull a day of conversations for a handle on a specific instance?
      instructions:
      - text: List conversation IDs for handle {networkhandle} on {networktype} instance {networkinstance}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkhandle: path.networkhandle
      - text: Get @{networkhandle}'s conversations in instance {networkinstance} of {networktype} ending {endEpochMillis}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkhandle: path.networkhandle
          endEpochMillis: query.endEpochMillis
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/instances/{networkinstance}/ids/{networkid}/split'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove Person attributes from a network ID
      effect: destructive
      questions:
      - How do I split a network identity off the Person it was merged into?
      - Can I remove Person attributes tied to one network ID on an instance?
      instructions:
      - text: Split network ID {networkid} on {networktype} instance {networkinstance} from its Person.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkid: path.networkid
      - text: Strip the Person attributes from user {networkid} in {networktype} instance {networkinstance}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkid: path.networkid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/networktype/ids/networkid/conversations/reactivate'].put
  update:
    x-apievangelist-phrasing:
      intent: Reactivate an author's conversations
      effect: write
      questions:
      - How do I reopen an author's conversations on the default network?
      - Can I leave a comment when reactivating an author's conversations?
      instructions:
      - text: Reactivate conversations for author {networkid} on {networktype}.
        slots:
          networktype: path.networktype
          networkid: path.networkid
      - text: Reactivate {networktype} author {networkid}'s conversations with comment {comment}.
        slots:
          networktype: path.networktype
          networkid: path.networkid
          comment: query.comment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/instances/{networkinstance}/ids/{networkId}/conversations/reactivate'].put
  update:
    x-apievangelist-phrasing:
      intent: Reactivate an author's conversations on an instance
      effect: write
      questions:
      - Can I reactivate an author's conversations on one specific network instance?
      - How do I reopen conversations for an author on a multi-instance network?
      instructions:
      - text: Reactivate conversations for author {networkid} on {networktype} instance {networkinstance}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkid: path.networkId
      - text: Reopen user {networkid}'s threads in instance {networkinstance} of {networktype} for page {pageId}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          networkid: path.networkId
          pageId: query.pageId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/networks/{networkType}/registrations'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a bot's registration details
      effect: read
      questions:
      - How do I check how my bot is registered with Khoros Care?
      - What callback URL and auth type is my bot registration using?
      instructions:
      - text: Show the {networktype} bot registration for external ID {externalId} and app {appId}.
        slots:
          networktype: path.networkType
          externalId: query.externalId
          appId: query.appId
      - text: Look up the registration details of bot app {appId} on {networktype}, external ID {externalId}.
        slots:
          networktype: path.networkType
          externalId: query.externalId
          appId: query.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networkType}/registrations'].put
  update:
    x-apievangelist-phrasing:
      intent: Register or update a bot registration
      effect: write
      questions:
      - Can I update my bot's callback URL or credentials on an existing registration?
      - Is there one call that registers a bot or updates it if it already exists?
      instructions:
      - text: Register or update bot app {appId} on {networktype} with callback {callbackUrl}.
        slots:
          networktype: path.networkType
          appId: requestBody.appId
          callbackUrl: requestBody.callbackUrl
      - text: Change the auth type for bot {externalId} on {networktype} to {authenticationType}.
        slots:
          networktype: path.networkType
          externalId: requestBody.externalId
          authenticationType: requestBody.authenticationType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networkType}/registrations'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new bot with Khoros Care
      effect: write
      questions:
      - How do I register a brand-new bot so it can take conversations?
      - What does a bot need to supply when it first registers?
      instructions:
      - text: Register a new bot {appId} on {networktype} for external ID {externalId} at {callbackUrl}.
        slots:
          networktype: path.networkType
          appId: requestBody.appId
          externalId: requestBody.externalId
          callbackUrl: requestBody.callbackUrl
      - text: Create a first-time {networktype} bot registration using basic auth user {username}.
        slots:
          networktype: path.networkType
          username: requestBody.username
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networkType}/registrations'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a bot registration
      effect: destructive
      questions:
      - How do I unregister a bot from Khoros Care?
      - Can I remove a single bot registration by app ID?
      instructions:
      - text: Delete the {networktype} bot registration for app {appId} and external ID {externalId}.
        slots:
          networktype: path.networkType
          appId: query.appId
          externalId: query.externalId
      - text: Unregister bot {appId} from {networktype} under external ID {externalId}.
        slots:
          networktype: path.networkType
          appId: query.appId
          externalId: query.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networkType}/allRegistrations'].get
  update:
    x-apievangelist-phrasing:
      intent: List bot registrations for an external ID
      effect: read
      questions:
      - Which bots are registered against one external ID?
      - Can I list every registration with just the external ID?
      instructions:
      - text: List all {networktype} bot registrations for external ID {externalId}.
        slots:
          networktype: path.networkType
          externalId: query.externalId
      - text: Show every bot app registered to {externalId} on {networktype}.
        slots:
          networktype: path.networkType
          externalId: query.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networkType}/authors/{authorId}/handoff'].put
  update:
    x-apievangelist-phrasing:
      intent: Hand a bot conversation to a Care agent
      effect: write
      questions:
      - How does my bot hand a conversation over to a human agent?
      - Can a bot escalate a customer to a live Care agent?
      instructions:
      - text: Hand author {authorId}'s {networktype} conversation from bot {externalId} to an agent.
        slots:
          networktype: path.networkType
          authorId: path.authorId
          externalId: query.externalId
      - text: Escalate customer {authorId} on {networktype} to a human, bot {externalId}.
        slots:
          networktype: path.networkType
          authorId: path.authorId
          externalId: query.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networkType}/authors/{authorId}/resolve'].put
  update:
    x-apievangelist-phrasing:
      intent: Resolve a conversation on behalf of a bot
      effect: write
      questions:
      - Can my bot close out a conversation as resolved for a given author?
      - How does a registered bot mark an author's conversation done?
      instructions:
      - text: Resolve author {authorId}'s {networktype} conversation for bot {externalId}.
        slots:
          networktype: path.networkType
          authorId: path.authorId
          externalId: query.externalId
      - text: Have bot {externalId} mark the chat with {authorId} on {networktype} as finished.
        slots:
          networktype: path.networkType
          authorId: path.authorId
          externalId: query.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/networks/{networktype}/instances/{networkinstance}/ids/{authorID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an author's conversation IDs for a date
      effect: read
      questions:
      - Which conversation IDs belong to an author during a specific 24-hour window?
      - Is the start time required when listing an author's conversations by date?
      instructions:
      - text: Get conversation IDs by author ID {authorId} on {networktype} instance {networkinstance} for the 24 hours from {startEpochMillis}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          authorId: path.authorID
          startEpochMillis: query.startEpochMillis
      - text: List author {authorId}'s conversations on instance {networkinstance} of {networktype} for the day starting {startEpochMillis}.
        slots:
          networktype: path.networktype
          networkinstance: path.networkinstance
          authorId: path.authorID
          startEpochMillis: query.startEpochMillis
      method: generated
      generated: '2026-10-02'