API Evangelist conversational phrasing for X Users API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for X Users API
  version: 1.0.0
extends: openapi/x-users-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: 44
- target: $.paths['/2/users'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up several users by ID
      effect: read
      questions:
      - Can I fetch profiles for a batch of user IDs at once?
      - Which profile fields can I request for multiple users by ID?
      instructions:
      - text: Get the users with IDs {ids}.
        slots:
          ids: query.ids
      - text: Look up user IDs {ids} with fields {fields}.
        slots:
          ids: query.ids
          fields: query.user.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/by'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up several users by username
      effect: read
      questions:
      - How do I turn a list of @handles into user profiles in one call?
      - Can I resolve multiple usernames to user IDs together?
      instructions:
      - text: Look up the users {usernames}.
        slots:
          usernames: query.usernames
      - text: 'Get profiles for these handles at once: {usernames}.'
        slots:
          usernames: query.usernames
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/by/username/{username}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one user by username (v2)
      effect: read
      questions:
      - What's the v2 way to get a single profile from an @handle?
      - Can I include a user's pinned post when looking them up by username?
      instructions:
      - text: Get the v2 profile for @{username}.
        slots:
          username: path.username
      - text: Look up @{username} and expand {expansions}.
        slots:
          username: path.username
          expansions: query.expansions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/me'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the authenticated user's profile
      effect: read
      questions:
      - Which account is my access token acting as?
      - How can I get my own user ID and profile?
      instructions:
      - text: Show my own profile.
      - text: Get my authenticated account with fields {fields}.
        slots:
          fields: query.user.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/public_keys'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Chat public keys for several users
      effect: read
      questions:
      - Can I fetch the X Chat encryption public keys for a batch of users?
      - What public keys are registered for multiple user IDs?
      instructions:
      - text: Get Chat public keys for users {ids}.
        slots:
          ids: query.ids
      - text: Fetch encryption keys for {ids} in one request.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/reposts_of_me'].get
  update:
    x-apievangelist-phrasing:
      intent: See reposts of my posts
      effect: read
      questions:
      - Which of my posts have other people reposted?
      - Can I page through reposts of my own content?
      instructions:
      - text: Show reposts of my posts.
      - text: List the latest {max_results} reposts of my content.
        slots:
          max_results: query.max_results
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search for users by keyword
      effect: read
      questions:
      - What accounts match a name or keyword?
      - Can I search users and page through the matches?
      instructions:
      - text: Search users for {query}.
        slots:
          query: query.query
      - text: Find up to {max_results} accounts matching {query}.
        slots:
          max_results: query.max_results
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one user by ID (v2)
      effect: read
      questions:
      - What's the v2 call for a single user profile by numeric ID?
      - Can I request specific profile fields for one user ID?
      instructions:
      - text: Get the v2 profile for user {id}.
        slots:
          id: path.id
      - text: Look up user {id} with fields {fields} on v2.
        slots:
          id: path.id
          fields: query.user.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/affiliates'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's affiliate accounts
      effect: read
      questions:
      - Which affiliated accounts are linked to an organization's profile?
      - Can I page through a user's affiliates?
      instructions:
      - text: List the affiliates of user {id}.
        slots:
          id: path.id
      - text: Show {max_results} affiliate accounts for {id}.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/blocking'].get
  update:
    x-apievangelist-phrasing:
      intent: List accounts I've blocked
      effect: read
      questions:
      - Which accounts have I blocked?
      - Can I export my full block list?
      instructions:
      - text: List the accounts user {id} is blocking.
        slots:
          id: path.id
      - text: Show {max_results} blocked accounts for {id}.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/bookmarks'].get
  update:
    x-apievangelist-phrasing:
      intent: List my bookmarked posts
      effect: read
      questions:
      - What posts have I bookmarked?
      - Can I export all my bookmarks through the API?
      instructions:
      - text: Show bookmarks for user {id}.
        slots:
          id: path.id
      - text: List the latest {max_results} posts {id} has bookmarked.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/bookmarks'].post
  update:
    x-apievangelist-phrasing:
      intent: Bookmark a post
      effect: write
      questions:
      - Can I save a post to my bookmarks programmatically?
      - Can I bookmark a post straight into a specific folder?
      instructions:
      - text: Bookmark post {tweet_id} for user {id}.
        slots:
          tweet_id: requestBody.tweet_id
          id: path.id
      - text: Save post {tweet_id} into bookmark folder {folder_id} for {id}.
        slots:
          tweet_id: requestBody.tweet_id
          folder_id: requestBody.folder_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/bookmarks/folders'].get
  update:
    x-apievangelist-phrasing:
      intent: List my bookmark folders
      effect: read
      questions:
      - Which bookmark folders have I created?
      - Can I list all bookmark folders on my account?
      instructions:
      - text: List bookmark folders for user {id}.
        slots:
          id: path.id
      - text: Show {max_results} of {id}'s bookmark folders.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/bookmarks/folders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a bookmark folder
      effect: write
      questions:
      - Can I organize my bookmarks by creating a new folder?
      - What's needed to make a named bookmark folder?
      instructions:
      - text: Create a bookmark folder called {name} for user {id}.
        slots:
          name: requestBody.name
          id: path.id
      - text: Make a new folder {name} in {id}'s bookmarks.
        slots:
          name: requestBody.name
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/bookmarks/folders/{folder_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List bookmarks in one folder
      effect: read
      questions:
      - Which posts are saved in a particular bookmark folder?
      - Can I read just one bookmark folder's contents?
      instructions:
      - text: Show the bookmarks in folder {folder_id} for user {id}.
        slots:
          folder_id: path.folder_id
          id: path.id
      - text: List {max_results} posts saved in bookmark folder {folder_id} of {id}.
        slots:
          max_results: query.max_results
          folder_id: path.folder_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/bookmarks/{tweet_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a post from my bookmarks
      effect: destructive
      questions:
      - What's the call to unbookmark a post?
      - Can I remove a saved post from my bookmarks by its ID?
      instructions:
      - text: Remove post {tweet_id} from {id}'s bookmarks.
        slots:
          tweet_id: path.tweet_id
          id: path.id
      - text: Unbookmark {tweet_id} for user {id}.
        slots:
          tweet_id: path.tweet_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/dm/block'].post
  update:
    x-apievangelist-phrasing:
      intent: Block a user from DMing me
      effect: write
      questions:
      - Can I stop a specific user from sending me Direct Messages?
      - Is there a DM-only block for an account?
      instructions:
      - text: Block DMs from user {id}.
        slots:
          id: path.id
      - text: Stop {id} from sending me direct messages.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/dm/unblock'].post
  update:
    x-apievangelist-phrasing:
      intent: Allow DMs from a user again
      effect: write
      questions:
      - How do I let a user I DM-blocked message me again?
      - Can I lift a Direct Message block on an account?
      instructions:
      - text: Unblock DMs from user {id}.
        slots:
          id: path.id
      - text: Let {id} send me direct messages again.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/followed_lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List the Lists a user follows
      effect: read
      questions:
      - Which Lists does an account follow?
      - Can I page through all Lists a user is following?
      instructions:
      - text: Show the Lists user {id} follows.
        slots:
          id: path.id
      - text: Get {max_results} Lists followed by {id}.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/followed_lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Follow a List
      effect: write
      questions:
      - How do I follow a List so its posts show up for me?
      - Can I follow someone else's public List?
      instructions:
      - text: Follow List {list_id} as user {id}.
        slots:
          list_id: requestBody.list_id
          id: path.id
      - text: Have {id} start following List {list_id}.
        slots:
          id: path.id
          list_id: requestBody.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/followed_lists/{list_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unfollow a List
      effect: destructive
      questions:
      - Is there a way to stop following a List?
      - Can I unfollow a List by its ID?
      instructions:
      - text: Unfollow List {list_id} for user {id}.
        slots:
          list_id: path.list_id
          id: path.id
      - text: Have {id} stop following List {list_id}.
        slots:
          id: path.id
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/followers'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's followers
      effect: read
      questions:
      - Who follows a given account?
      - Can I page through all of a user's followers?
      instructions:
      - text: List the followers of user {id}.
        slots:
          id: path.id
      - text: Get {max_results} followers of {id}.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/following'].get
  update:
    x-apievangelist-phrasing:
      intent: List accounts a user follows
      effect: read
      questions:
      - Which accounts does a user follow?
      - Can I get the full following list for an account?
      instructions:
      - text: List the accounts user {id} follows.
        slots:
          id: path.id
      - text: Get {max_results} accounts that {id} is following.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/following'].post
  update:
    x-apievangelist-phrasing:
      intent: Follow a user
      effect: write
      questions:
      - Can I follow another account via the API?
      - Can my app follow a user on behalf of the signed-in account?
      instructions:
      - text: Follow user {target_user_id} as {id}.
        slots:
          target_user_id: requestBody.target_user_id
          id: path.id
      - text: Have {id} follow {target_user_id}.
        slots:
          id: path.id
          target_user_id: requestBody.target_user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/liked_tweets'].get
  update:
    x-apievangelist-phrasing:
      intent: List posts a user has liked
      effect: read
      questions:
      - Which posts has an account liked?
      - Can I page through a user's liked posts?
      instructions:
      - text: Show posts liked by user {id}.
        slots:
          id: path.id
      - text: Get the last {max_results} posts {id} liked.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/likes'].post
  update:
    x-apievangelist-phrasing:
      intent: Like a post
      effect: write
      questions:
      - Is liking a post possible through the API?
      - Can my app like a post for the signed-in user?
      instructions:
      - text: Like post {tweet_id} as user {id}.
        slots:
          tweet_id: requestBody.tweet_id
          id: path.id
      - text: Have {id} like {tweet_id}.
        slots:
          id: path.id
          tweet_id: requestBody.tweet_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/likes/{tweet_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlike a post
      effect: destructive
      questions:
      - Can I take back a like I gave a post?
      - Can I undo a like by the post's ID?
      instructions:
      - text: Unlike post {tweet_id} for user {id}.
        slots:
          tweet_id: path.tweet_id
          id: path.id
      - text: Remove {id}'s like on {tweet_id}.
        slots:
          id: path.id
          tweet_id: path.tweet_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/list_memberships'].get
  update:
    x-apievangelist-phrasing:
      intent: List the Lists a user belongs to
      effect: read
      questions:
      - Which Lists has an account been added to?
      - Can I see every List that includes a particular user?
      instructions:
      - text: Show the Lists that include user {id}.
        slots:
          id: path.id
      - text: Get {max_results} List memberships for {id}.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/mentions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get posts mentioning a user
      effect: read
      questions:
      - Who has mentioned an account recently?
      - Can I get a user's mentions within a date range?
      instructions:
      - text: Show posts mentioning user {id}.
        slots:
          id: path.id
      - text: Get mentions of {id} between {start_time} and {end_time}.
        slots:
          id: path.id
          start_time: query.start_time
          end_time: query.end_time
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/muting'].get
  update:
    x-apievangelist-phrasing:
      intent: List accounts I've muted
      effect: read
      questions:
      - Which accounts have I muted?
      - Can I export my mute list?
      instructions:
      - text: List the accounts user {id} has muted.
        slots:
          id: path.id
      - text: Show {max_results} muted accounts for {id}.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/muting'].post
  update:
    x-apievangelist-phrasing:
      intent: Mute a user
      effect: write
      questions:
      - How do I mute an account so I stop seeing their posts?
      - Can my app mute someone for the signed-in user?
      instructions:
      - text: Mute user {target_user_id} for {id}.
        slots:
          target_user_id: requestBody.target_user_id
          id: path.id
      - text: Have {id} mute {target_user_id}.
        slots:
          id: path.id
          target_user_id: requestBody.target_user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/owned_lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List the Lists a user owns
      effect: read
      questions:
      - Which Lists has an account created?
      - Can I page through all Lists a user owns?
      instructions:
      - text: Show the Lists owned by user {id}.
        slots:
          id: path.id
      - text: Get {max_results} Lists that {id} created.
        slots:
          max_results: query.max_results
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/pinned_lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's pinned Lists
      effect: read
      questions:
      - Which Lists has a user pinned?
      - Can I see my pinned Lists with their owner details?
      instructions:
      - text: Show the pinned Lists of user {id}.
        slots:
          id: path.id
      - text: Get {id}'s pinned Lists with fields {fields}.
        slots:
          id: path.id
          fields: query.list.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/pinned_lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Pin a List
      effect: write
      questions:
      - Can I pin a List to the top of my Lists?
      - Can I pin a List by its ID for the signed-in user?
      instructions:
      - text: Pin List {list_id} for user {id}.
        slots:
          list_id: requestBody.list_id
          id: path.id
      - text: Have {id} pin List {list_id}.
        slots:
          id: path.id
          list_id: requestBody.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/pinned_lists/{list_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unpin a List
      effect: destructive
      questions:
      - What removes a List from my pinned set?
      - Can I remove a List from my pinned Lists?
      instructions:
      - text: Unpin List {list_id} for user {id}.
        slots:
          list_id: path.list_id
          id: path.id
      - text: Have {id} unpin List {list_id}.
        slots:
          id: path.id
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/public_keys'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one user's Chat public keys
      effect: read
      questions:
      - What Chat encryption keys has a single user registered?
      - Where do I get one person's public key before messaging them in XChat?
      instructions:
      - text: Get the Chat public keys of user {id}.
        slots:
          id: path.id
      - text: Show {id}'s registered encryption keys.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/retweets'].post
  update:
    x-apievangelist-phrasing:
      intent: Repost a post
      effect: write
      questions:
      - How do I repost a post to my followers?
      - Can my app repost something for the signed-in user?
      instructions:
      - text: Repost post {tweet_id} as user {id}.
        slots:
          tweet_id: requestBody.tweet_id
          id: path.id
      - text: Have {id} repost {tweet_id}.
        slots:
          id: path.id
          tweet_id: requestBody.tweet_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/retweets/{source_tweet_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Undo a repost
      effect: destructive
      questions:
      - Is it possible to undo a repost?
      - Can I remove my repost of a post by its ID?
      instructions:
      - text: Undo the repost of {source_tweet_id} for user {id}.
        slots:
          source_tweet_id: path.source_tweet_id
          id: path.id
      - text: Have {id} unrepost {source_tweet_id}.
        slots:
          id: path.id
          source_tweet_id: path.source_tweet_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/timelines/reverse_chronological'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's home timeline
      effect: read
      questions:
      - What's in my home timeline in reverse chronological order?
      - Can I pull my home feed for a time range, excluding some post types?
      instructions:
      - text: Show the home timeline for user {id}.
        slots:
          id: path.id
      - text: Get {id}'s home feed from {start_time} to {end_time} excluding {exclude}.
        slots:
          id: path.id
          start_time: query.start_time
          end_time: query.end_time
          exclude: query.exclude
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{id}/tweets'].get
  update:
    x-apievangelist-phrasing:
      intent: Get posts written by a user
      effect: read
      questions:
      - What has a particular account posted recently?
      - Can I fetch a user's own posts while excluding some post types?
      instructions:
      - text: Show the posts authored by user {id}.
        slots:
          id: path.id
      - text: Get {id}'s posts since post {since_id}, excluding {exclude}.
        slots:
          id: path.id
          since_id: query.since_id
          exclude: query.exclude
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{source_user_id}/following/{target_user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unfollow a user
      effect: destructive
      questions:
      - What's the way to unfollow an account?
      - Can my app unfollow someone on behalf of the signed-in user?
      instructions:
      - text: Unfollow {target_user_id} as {source_user_id}.
        slots:
          target_user_id: path.target_user_id
          source_user_id: path.source_user_id
      - text: Have {source_user_id} stop following {target_user_id}.
        slots:
          source_user_id: path.source_user_id
          target_user_id: path.target_user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/users/{source_user_id}/muting/{target_user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unmute a user
      effect: destructive
      questions:
      - Can I unmute an account I muted earlier?
      - Can I start seeing a muted user's posts again?
      instructions:
      - text: Unmute {target_user_id} for {source_user_id}.
        slots:
          target_user_id: path.target_user_id
          source_user_id: path.source_user_id
      - text: Have {source_user_id} unmute {target_user_id}.
        slots:
          source_user_id: path.source_user_id
          target_user_id: path.target_user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a user by ID (unversioned endpoint)
      effect: read
      questions:
      - Is there a legacy non-/2 route to look up a user by ID?
      - Which unversioned endpoint returns a user from their numeric ID?
      instructions:
      - text: Look up user {id} via the unversioned /users endpoint.
        slots:
          id: path.id
      - text: Use the legacy user-by-ID route for {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/by/username/{username}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a user by username (unversioned)
      effect: read
      questions:
      - Does the older unversioned API still resolve an @handle to a profile?
      - Which unversioned endpoint returns a profile for a username?
      instructions:
      - text: Look up @{username} via the unversioned /users/by/username route.
        slots:
          username: path.username
      - text: Use the legacy user-by-username endpoint for {username}.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-26'