# 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 Stream API
  version: 1.0.0
extends: openapi/khoros-ai-stream-api-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: 25
- target: $.paths['/{account}/{streamName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a stream's approved content
      effect: read
      questions:
      - What content has been approved in one of my Khoros streams?
      - Can I pull every approved post from a stream with full-length tweet text?
      instructions:
      - text: Get the approved content in stream {streamName} for account {account}.
        slots:
          account: path.account
          streamName: path.streamName
      - text: Pull approved items from {account}/{streamName} using tweet mode {tweet_mode}.
        slots:
          account: path.account
          streamName: path.streamName
          tweet_mode: query.tweet_mode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?limit'].get
  update:
    x-apievangelist-phrasing:
      intent: Pull a set number of approved stream items
      effect: read
      questions:
      - Can I cap how many approved items a stream returns in one call?
      - How many entities can I ask a stream for at once?
      instructions:
      - text: Fetch only {limit} approved items from stream {streamName} on account {account}.
        slots:
          account: path.account
          streamName: path.streamName
          limit: query.limit
      - text: Give me the latest {limit} entries in {account}/{streamName}.
        slots:
          account: path.account
          streamName: path.streamName
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?since_id'].get
  update:
    x-apievangelist-phrasing:
      intent: Get newest stream items after a given entity
      effect: read
      questions:
      - How do I poll a stream for only the newest items approved after one I already have, favoring real-time?
      - Will the since_id filter skip items to keep me close to real time?
      instructions:
      - text: Get items approved in {account}/{streamName} since entity {since_id}, newest first.
        slots:
          account: path.account
          streamName: path.streamName
          since_id: query.since_id
      - text: Poll {account}/{streamName} for anything newer than {since_id} in near real time.
        slots:
          account: path.account
          streamName: path.streamName
          since_id: query.since_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?from_id'].get
  update:
    x-apievangelist-phrasing:
      intent: Page through stream items after an entity, no gaps
      effect: read
      questions:
      - Can I fetch everything approved after a specific entity without skipping any items?
      - What is the gap-free way to catch up on a stream from a known entity ID?
      instructions:
      - text: Catch up on {account}/{streamName} starting from entity {from_id} without skipping any.
        slots:
          account: path.account
          streamName: path.streamName
          from_id: query.from_id
      - text: Walk forward through every approval in {account}/{streamName} after {from_id}.
        slots:
          account: path.account
          streamName: path.streamName
          from_id: query.from_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?start_id'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stream items approved before an entity
      effect: read
      questions:
      - How do I page backwards through older approved items in a stream?
      - Can I get only the entities approved before a given entity ID?
      instructions:
      - text: List items in {account}/{streamName} approved before entity {start_id}.
        slots:
          account: path.account
          streamName: path.streamName
          start_id: query.start_id
      - text: Load the older page of {account}/{streamName} preceding {start_id}.
        slots:
          account: path.account
          streamName: path.streamName
          start_id: query.start_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?callback'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stream content wrapped as JSONP
      effect: read
      questions:
      - Can a stream response be wrapped in a JavaScript callback for JSONP?
      - Is there JSONP support for embedding stream content in a web page?
      instructions:
      - text: Return stream {streamName} for account {account} as JSONP with a callback function.
        slots:
          account: path.account
          streamName: path.streamName
      - text: Wrap the {account}/{streamName} feed in a JavaScript callback so my page can embed it.
        slots:
          account: path.account
          streamName: path.streamName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?geo_hint'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stream items with geohint data
      effect: read
      questions:
      - Can stream items include geohinting location data?
      - How do I turn on geo hints when pulling approved stream content?
      instructions:
      - text: Pull {account}/{streamName} with geo hint set to {geo_hint}.
        slots:
          account: path.account
          streamName: path.streamName
          geo_hint: query.geo_hint
      - text: Add location geohints to the items from stream {streamName} on {account}.
        slots:
          account: path.account
          streamName: path.streamName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?page_links'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stream items with product page links
      effect: read
      questions:
      - Can each stream entity come back with product hinting links attached?
      - How do I enable page links for products mentioned in stream items?
      instructions:
      - text: Fetch {account}/{streamName} with product page links enabled ({page_links}).
        slots:
          account: path.account
          streamName: path.streamName
          page_links: query.page_links
      - text: Attach product hints to every entity in stream {streamName} of account {account}.
        slots:
          account: path.account
          streamName: path.streamName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?replies'].get
  update:
    x-apievangelist-phrasing:
      intent: Include replied-to posts in stream items
      effect: read
      questions:
      - Can I see the original post that each stream item was replying to?
      - Which option fills the in_reply_to property on stream entities?
      instructions:
      - text: Get {account}/{streamName} including the posts each item replied to (replies={replies}).
        slots:
          account: path.account
          streamName: path.streamName
          replies: query.replies
      - text: Show the parent post alongside each reply in {account}/{streamName}.
        slots:
          account: path.account
          streamName: path.streamName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?network'].get
  update:
    x-apievangelist-phrasing:
      intent: Filter stream items by social network
      effect: read
      questions:
      - Can I limit a stream to items from just one social network?
      - How do I get only Instagram or only Twitter content out of a mixed stream?
      instructions:
      - text: Get approved items from network {network} in stream {streamName} for account {account}.
        slots:
          account: path.account
          streamName: path.streamName
          network: query.network
      - text: Show only {network} posts from {account}/{streamName}.
        slots:
          account: path.account
          streamName: path.streamName
          network: query.network
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?include_entities'].get
  update:
    x-apievangelist-phrasing:
      intent: Include entity objects on tweets (XML)
      effect: read
      questions:
      - Can tweets in an XML stream response carry their links and media entities?
      - What does include_entities add to tweets on the XML endpoint?
      instructions:
      - text: Return XML for {account}/{streamName} with tweet entities included ({include_entities}).
        slots:
          account: path.account
          streamName: path.streamName
          include_entities: query.include_entities
      - text: Include the links and media objects on each tweet in the {account}/{streamName} XML feed.
        slots:
          account: path.account
          streamName: path.streamName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?reverse'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stream items in chronological order
      effect: read
      questions:
      - Can I get the oldest approved items on top instead of the newest?
      - Is the default stream order reverse chronological by approval time?
      instructions:
      - text: Show {account}/{streamName} in oldest-first approval order (reverse={reverse}).
        slots:
          account: path.account
          streamName: path.streamName
          reverse: query.reverse
      - text: Flip the order of stream {streamName} on {account} so earliest approvals come first.
        slots:
          account: path.account
          streamName: path.streamName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?strip_links'].get
  update:
    x-apievangelist-phrasing:
      intent: Strip trailing URLs from stream item text
      effect: read
      questions:
      - Can I remove the trailing links from the text of stream posts?
      - Is there a way to get cleaner post text without URLs at the end?
      instructions:
      - text: Get {account}/{streamName} with trailing links stripped from text ({strip_links}).
        slots:
          account: path.account
          streamName: path.streamName
          strip_links: query.strip_links
      - text: Clean the end-of-text URLs off posts in stream {streamName} for {account}.
        slots:
          account: path.account
          streamName: path.streamName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?keywords'].get
  update:
    x-apievangelist-phrasing:
      intent: Filter stream items by keyword
      effect: read
      questions:
      - How do I get only the stream items that mention certain keywords?
      - Can a stream be filtered down to posts containing a word or phrase?
      instructions:
      - text: Find items in {account}/{streamName} that contain {keywords}.
        slots:
          account: path.account
          streamName: path.streamName
          keywords: query.keywords
      - text: Show posts mentioning {keywords} in stream {streamName} on account {account}.
        slots:
          account: path.account
          streamName: path.streamName
          keywords: query.keywords
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?from'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stream items by one author
      effect: read
      questions:
      - Can I see only the posts one author contributed to a stream?
      - Does the author filter need to be lowercase?
      instructions:
      - text: Show items in {account}/{streamName} written by author {author}.
        slots:
          account: path.account
          streamName: path.streamName
          author: query.from
      - text: Filter stream {streamName} on {account} to posts from {author} only.
        slots:
          account: path.account
          streamName: path.streamName
          author: query.from
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?timeframe[start]'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stream items created after a time
      effect: read
      questions:
      - How do I get stream items created after a certain date?
      - Does the start of the timeframe filter take seconds or milliseconds?
      instructions:
      - text: Get items in {account}/{streamName} created after unix time {start}.
        slots:
          account: path.account
          streamName: path.streamName
          start: query.timeframe[start]
      - text: Show posts in stream {streamName} for {account} from {start} onward.
        slots:
          account: path.account
          streamName: path.streamName
          start: query.timeframe[start]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}/{streamName}?timeframe[finish]'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stream items created before a time
      effect: read
      questions:
      - Can I limit a stream to items created before a cutoff time?
      - What time format does the timeframe finish filter expect?
      instructions:
      - text: Get items in {account}/{streamName} created before unix time {finish}.
        slots:
          account: path.account
          streamName: path.streamName
          finish: query.timeframe[finish]
      - text: Show stream {streamName} posts on {account} up until {finish}.
        slots:
          account: path.account
          streamName: path.streamName
          finish: query.timeframe[finish]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get activity meta for an account's streams
      effect: read
      questions:
      - What are the entity counts and activity rates across my account's streams?
      - Where can I see summary meta-information for all streams on an account?
      instructions:
      - text: Get the stream meta summary for account {account}.
        slots:
          account: path.account
      - text: Show entity counts and activity rates for every stream under {account}.
        slots:
          account: path.account
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}.json?streams'].get
  update:
    x-apievangelist-phrasing:
      intent: Get meta info for selected streams of an account
      effect: read
      questions:
      - Can I get account meta-information for just a few named streams?
      - How do I narrow account-level stream stats to a comma-separated list of streams?
      instructions:
      - text: Get account {account} meta info for streams {streams}.
        slots:
          account: path.account
          streams: query.streams
      - text: Summarize activity on {streams} only, within account {account}.
        slots:
          account: path.account
          streams: query.streams
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}.json?num_minutes'].get
  update:
    x-apievangelist-phrasing:
      intent: Get minutes of activity for an account
      effect: read
      questions:
      - How many minutes of activity can I pull in an account's meta data?
      - Can I choose how many minutes of activity an account's stream meta returns?
      instructions:
      - text: Show {num_minutes} minutes of activity for account {account}.
        slots:
          account: path.account
          num_minutes: query.num_minutes
      - text: Give me the per-minute activity history across account {account}.
        slots:
          account: path.account
      method: generated
      generated: '2026-10-02'
- target: $.paths['/{account}.json?num_trends'].get
  update:
    x-apievangelist-phrasing:
      intent: Get trending topics per bucket for an account
      effect: read
      questions:
      - What are the top trends across my account's streams?
      - Can I set how many trends come back in each bucket?
      instructions:
      - text: Return {num_trends} trends per bucket for account {account}.
        slots:
          account: path.account
          num_trends: query.num_trends
      - text: What is trending in account {account} right now? List the trends.
        slots:
          account: path.account
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}.json?disregard'].get
  update:
    x-apievangelist-phrasing:
      intent: Exclude certain trends from account meta
      effect: read
      questions:
      - Can I hide specific trends from my account's trend buckets?
      - Will excluding trends still try to fill the requested trend count?
      instructions:
      - text: Get account {account} trends but leave out {disregard}.
        slots:
          account: path.account
          disregard: query.disregard
      - text: Drop the trend {disregard} from the trend buckets for {account}.
        slots:
          account: path.account
          disregard: query.disregard
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}.json?start'].get
  update:
    x-apievangelist-phrasing:
      intent: Get account activity data from a start time
      effect: read
      questions:
      - How do I get an account's activity data starting at a particular moment?
      - Can account activity meta begin at a unix timestamp I choose?
      instructions:
      - text: Get activity data for account {account} starting at unix time {start}.
        slots:
          account: path.account
          start: query.start
      - text: Begin the activity timeline for {account} at {start}.
        slots:
          account: path.account
          start: query.start
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}.json?finish'].get
  update:
    x-apievangelist-phrasing:
      intent: Get account activity data up to an end time
      effect: read
      questions:
      - Can I end an account's activity data at a specific point in time?
      - Is there an end-time option for account-level activity meta?
      instructions:
      - text: Get activity data for account {account} ending at a set time.
        slots:
          account: path.account
      - text: Cut off the activity timeline for {account} at the end time I give.
        slots:
          account: path.account
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{account}.json?streams_with_topics'].get
  update:
    x-apievangelist-phrasing:
      intent: List account streams with or without topics
      effect: read
      questions:
      - Which of my account's streams have topics configured?
      - Can I find streams that are missing topic configuration?
      instructions:
      - text: List streams on account {account} filtered by topic configuration {streams_with_topics}.
        slots:
          account: path.account
          streams_with_topics: query.streams_with_topics
      - text: Show which streams in {account} still have no topics set up.
        slots:
          account: path.account
      method: generated
      generated: '2026-10-01'