# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for X Posts API
  version: 1.0.0
extends: openapi/x-posts-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: 19
- target: $.paths['/2/tweets'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up several posts by ID
      effect: read
      questions:
      - Can I fetch a batch of posts in a single request?
      - What author and media details can I include when looking up multiple post IDs?
      instructions:
      - text: Get the posts with IDs {ids}.
        slots:
          ids: query.ids
      - text: Look up posts {ids} and expand {expansions}.
        slots:
          ids: query.ids
          expansions: query.expansions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a post
      effect: write
      questions:
      - What's the v2 call to publish a post?
      - Can I post a poll, a quote post, or restrict who can reply?
      - Is there a way to disclose AI-generated media or a paid partnership when posting?
      instructions:
      - text: Post {text}.
        slots:
          text: requestBody.text
      - text: Quote post {quote_tweet_id} with the comment {text}.
        slots:
          quote_tweet_id: requestBody.quote_tweet_id
          text: requestBody.text
      - text: Post {text} to community {community_id}.
        slots:
          text: requestBody.text
          community_id: requestBody.community_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/analytics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get engagement analytics for posts
      effect: read
      questions:
      - How did my posts perform over a given time window?
      - Can I break post analytics down by day or hour?
      instructions:
      - text: Show analytics for posts {ids} from {start_time} to {end_time}.
        slots:
          ids: query.ids
          start_time: query.start_time
          end_time: query.end_time
      - text: Get {granularity} engagement metrics for {ids} between {start_time} and {end_time}.
        slots:
          granularity: query.granularity
          ids: query.ids
          start_time: query.start_time
          end_time: query.end_time
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/counts/all'].get
  update:
    x-apievangelist-phrasing:
      intent: Count matching posts across the full archive
      effect: read
      questions:
      - How many posts mentioned a keyword across all of X's history?
      - Can I get a full-archive post volume over time grouped by day?
      instructions:
      - text: Count all-time posts matching {query}.
        slots:
          query: query.query
      - text: Get {granularity} full-archive post counts for {query} from {start_time} to {end_time}.
        slots:
          granularity: query.granularity
          query: query.query
          start_time: query.start_time
          end_time: query.end_time
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/counts/recent'].get
  update:
    x-apievangelist-phrasing:
      intent: Count matching posts from the last 7 days
      effect: read
      questions:
      - How many posts matched my query recently?
      - Can I chart recent post volume for a hashtag by hour?
      instructions:
      - text: Count recent posts matching {query}.
        slots:
          query: query.query
      - text: Get {granularity} counts of last-week posts for {query}.
        slots:
          granularity: query.granularity
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/search/all'].get
  update:
    x-apievangelist-phrasing:
      intent: Search the full post archive (v2)
      effect: read
      questions:
      - Where can I search posts going back to the beginning of X on the v2 API?
      - Can a full-archive search be limited to a date range and sorted a chosen way?
      instructions:
      - text: Search the full v2 archive for posts matching {query}.
        slots:
          query: query.query
      - text: Search all-time posts for {query} between {start_time} and {end_time} sorted by {sort_order}.
        slots:
          query: query.query
          start_time: query.start_time
          end_time: query.end_time
          sort_order: query.sort_order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/search/recent'].get
  update:
    x-apievangelist-phrasing:
      intent: Search posts from the last 7 days
      effect: read
      questions:
      - What have people posted about a topic recently?
      - Can I get only recent posts newer than a certain post ID?
      instructions:
      - text: Search the past week's posts for {query}.
        slots:
          query: query.query
      - text: Find recent posts matching {query} newer than {since_id}.
        slots:
          query: query.query
          since_id: query.since_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single post
      effect: read
      questions:
      - Can I retrieve one post and its metrics from its ID?
      - Can I include the author's profile when fetching a single post?
      instructions:
      - text: Get post {id}.
        slots:
          id: path.id
      - text: Show post {id} with fields {fields}.
        slots:
          id: path.id
          fields: query.post.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a post
      effect: destructive
      questions:
      - How can I delete one of my posts?
      - Is deleting a post through the API permanent?
      instructions:
      - text: Delete post {id}.
        slots:
          id: path.id
      - text: Remove my post {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/{id}/liking_users'].get
  update:
    x-apievangelist-phrasing:
      intent: See who liked a post
      effect: read
      questions:
      - Who liked a particular post?
      - Can I page through every user who liked a post?
      instructions:
      - text: List the users who liked post {id}.
        slots:
          id: path.id
      - text: Show {max_results} accounts that liked {id}.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/{id}/quote_tweets'].get
  update:
    x-apievangelist-phrasing:
      intent: Get quote posts of a post
      effect: read
      questions:
      - What are people saying when they quote a specific post?
      - Can I exclude certain kinds of posts when listing quote posts?
      instructions:
      - text: Show the quote posts of {id}.
        slots:
          id: path.id
      - text: List quotes of post {id} excluding {exclude}.
        slots:
          id: path.id
          exclude: query.exclude
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/{id}/retweeted_by'].get
  update:
    x-apievangelist-phrasing:
      intent: See who reposted a post
      effect: read
      questions:
      - Which users reposted a given post?
      - Can I get the accounts that shared a post with a repost?
      instructions:
      - text: List the users who reposted post {id}.
        slots:
          id: path.id
      - text: Show {max_results} accounts that reposted {id}.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/{id}/retweets'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the repost objects of a post
      effect: read
      questions:
      - Can I retrieve the actual repost posts of a post rather than just the users?
      - What media and poll details come with a post's reposts?
      instructions:
      - text: Get the repost posts of {id}.
        slots:
          id: path.id
      - text: Fetch {max_results} repost entries for post {id} with their media.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/tweets/{tweet_id}/hidden'].put
  update:
    x-apievangelist-phrasing:
      intent: Hide or unhide a reply
      effect: write
      questions:
      - How do I hide an abusive reply to one of my conversations?
      - Can I unhide a reply I hid earlier?
      instructions:
      - text: Hide reply {tweet_id}.
        slots:
          tweet_id: path.tweet_id
      - text: Set hidden to {hidden} on reply {tweet_id}.
        slots:
          hidden: requestBody.hidden
          tweet_id: path.tweet_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tweets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a post (unversioned endpoint)
      effect: write
      questions:
      - Is there an older unversioned /tweets route for creating a post?
      - What does the legacy non-/2 create-post endpoint do?
      instructions:
      - text: Create a new post using the unversioned /tweets endpoint.
      - text: Publish a post through the legacy create-post route.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tweets/search/all'].get
  update:
    x-apievangelist-phrasing:
      intent: Full-archive search (unversioned endpoint)
      effect: read
      questions:
      - Is there a legacy non-/2 route for full-archive post search?
      - Which unversioned endpoint runs a full-archive search?
      instructions:
      - text: Run a full-archive search for {query} on the unversioned endpoint.
        slots:
          query: query.query
      - text: Use the legacy /tweets/search/all route to search {query}.
        slots:
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tweets/search/stream'].get
  update:
    x-apievangelist-phrasing:
      intent: Connect to the filtered stream (unversioned)
      effect: read
      questions:
      - Is there an unversioned route for the near real-time filtered stream?
      - Where does the legacy non-/2 filtered stream connect?
      instructions:
      - text: Connect to the filtered stream on the unversioned endpoint.
      - text: Open the legacy /tweets/search/stream connection.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tweets/search/stream/rules'].get
  update:
    x-apievangelist-phrasing:
      intent: List filtered stream rules (unversioned)
      effect: read
      questions:
      - Which legacy unversioned route lists my active filtered stream rules?
      - Can I read my stream rules without the /2 prefix?
      instructions:
      - text: List my active filtered stream rules from the unversioned endpoint.
      - text: Show stream rules using the legacy /tweets/search/stream/rules route.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tweets/search/stream/rules'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or delete stream rules (unversioned)
      effect: write
      questions:
      - Is there an unversioned route to add or remove filtered stream rules?
      - What does the legacy non-/2 stream rules POST change?
      instructions:
      - text: Update my filtered stream rules through the unversioned endpoint.
      - text: Add or delete rules via the legacy /tweets/search/stream/rules POST.
      method: generated
      generated: '2026-09-26'