# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for GitHub v3 REST Users API
  version: 1.0.0
extends: openapi/github-users-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 36
- target: $.paths['/user'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my own account profile
      effect: read
      questions:
      - Who am I signed in as, according to the token I'm using?
      - What does my own profile look like, including private details my token scope allows?
      instructions:
      - text: Show my own signed-in user profile.
      - text: Tell me which account this token belongs to.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update my own profile
      effect: write
      questions:
      - Can I change my display name, bio or location on my profile through the API?
      - How do I mark myself as available for hire on my profile?
      instructions:
      - text: Set my profile bio to {bio}.
        slots:
          bio: requestBody.bio
      - text: Update my profile name to {name} and my location to {location}.
        slots:
          name: requestBody.name
          location: requestBody.location
      - text: Change my profile company to {company} and my blog link to {blog}.
        slots:
          company: requestBody.company
          blog: requestBody.blog
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/emails'].get
  update:
    x-apievangelist-phrasing:
      intent: List all email addresses on my account
      effect: read
      questions:
      - Which email addresses are attached to my account, and which one is public?
      - Are all the emails on my account verified?
      instructions:
      - text: List every email address on my account, including private ones.
      - text: Show all my account emails and which is primary.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/emails'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an email address to my account
      effect: write
      questions:
      - How do I add another email address to my account?
      - What token scope is needed to attach a new email to my user?
      instructions:
      - text: Add a new email address to my account.
      - text: Attach an additional email to my signed-in user.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/emails'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an email address from my account
      effect: destructive
      questions:
      - Can I remove an old email address from my account?
      - What scope do I need to detach an email from my user?
      instructions:
      - text: Delete an email address from my account.
      - text: Remove an outdated email from my signed-in user.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/followers'].get
  update:
    x-apievangelist-phrasing:
      intent: List my followers
      effect: read
      questions:
      - Who follows me?
      - How many people are following my account?
      instructions:
      - text: List the people who follow me.
      - text: Show my followers, {per_page} per page.
        slots:
          per_page: query.per_page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/following'].get
  update:
    x-apievangelist-phrasing:
      intent: List the people I follow
      effect: read
      questions:
      - Which accounts am I following?
      - Can I get the full list of users I follow?
      instructions:
      - text: List everyone I follow.
      - text: Show page {page} of the accounts I'm following.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/following/{username}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if I follow a user
      effect: read
      questions:
      - Am I already following a particular user?
      - Can I confirm whether a certain person is on my following list?
      instructions:
      - text: Check whether I follow {username}.
        slots:
          username: path.username
      - text: Tell me if {username} is someone I'm following.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/following/{username}'].put
  update:
    x-apievangelist-phrasing:
      intent: Follow a user
      effect: write
      questions:
      - How do I follow another developer from the API?
      - Is there a special Content-Length requirement when following someone?
      instructions:
      - text: Follow {username}.
        slots:
          username: path.username
      - text: Start following the account {username} from my user.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/following/{username}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unfollow a user
      effect: destructive
      questions:
      - Can I stop following someone through the API?
      - What scope does unfollowing a user require?
      instructions:
      - text: Unfollow {username}.
        slots:
          username: path.username
      - text: Stop following the account {username}.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/gpg_keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List my GPG keys
      effect: read
      questions:
      - Which GPG keys have I registered for signing commits?
      - What scope is needed to read the GPG keys on my own account?
      instructions:
      - text: List the GPG keys on my account.
      - text: Show all my registered GPG signing keys, {per_page} per page.
        slots:
          per_page: query.per_page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/gpg_keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a GPG key to my account
      effect: write
      questions:
      - How do I upload a GPG public key so my signed commits show as verified?
      - Can I give a GPG key a friendly name when I add it?
      instructions:
      - text: 'Add this armored GPG public key to my account: {armored_public_key}.'
        slots:
          armored_public_key: requestBody.armored_public_key
      - text: Register GPG key {armored_public_key} on my account named {name}.
        slots:
          armored_public_key: requestBody.armored_public_key
          name: requestBody.name
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/gpg_keys/{gpg_key_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of one of my GPG keys
      effect: read
      questions:
      - What are the extended details of a single GPG key on my account?
      - Which emails and subkeys belong to one of my GPG keys?
      instructions:
      - text: Get my GPG key {gpg_key_id}.
        slots:
          gpg_key_id: path.gpg_key_id
      - text: Show full details for GPG key id {gpg_key_id} on my account.
        slots:
          gpg_key_id: path.gpg_key_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/gpg_keys/{gpg_key_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one of my GPG keys
      effect: destructive
      questions:
      - Can I remove a compromised GPG key from my account?
      - What happens to commit verification if I delete a GPG key?
      instructions:
      - text: Delete my GPG key {gpg_key_id}.
        slots:
          gpg_key_id: path.gpg_key_id
      - text: Remove GPG key {gpg_key_id} from my account.
        slots:
          gpg_key_id: path.gpg_key_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List my SSH authentication keys
      effect: read
      questions:
      - Which SSH keys can currently access my account?
      - How do I audit the public SSH keys I've added for git access?
      instructions:
      - text: List the public SSH keys on my account.
      - text: Show my SSH access keys, page {page}.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an SSH authentication key to my account
      effect: write
      questions:
      - How do I add a new SSH key so a laptop can push over SSH?
      - Can I label a new SSH access key with a title?
      instructions:
      - text: Add the public SSH key {key} to my account for authentication.
        slots:
          key: requestBody.key
      - text: Register SSH access key {key} with title {title}.
        slots:
          key: requestBody.key
          title: requestBody.title
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/keys/{key_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of my SSH authentication keys
      effect: read
      questions:
      - What are the details of one specific SSH access key on my account?
      - When was a given SSH key of mine added?
      instructions:
      - text: Get my public SSH key {key_id}.
        slots:
          key_id: path.key_id
      - text: Show details of SSH access key {key_id} on my account.
        slots:
          key_id: path.key_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/keys/{key_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one of my SSH authentication keys
      effect: destructive
      questions:
      - Can I revoke an SSH key from a lost machine?
      - What's the way to remove an old SSH access key from my account?
      instructions:
      - text: Delete my public SSH key {key_id}.
        slots:
          key_id: path.key_id
      - text: Remove SSH access key {key_id} from my account.
        slots:
          key_id: path.key_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/public_emails'].get
  update:
    x-apievangelist-phrasing:
      intent: List my publicly visible email addresses
      effect: read
      questions:
      - Which of my email addresses is visible to the public?
      - What email do other people see on my profile?
      instructions:
      - text: List only my publicly visible email addresses.
      - text: Show the email that is public on my profile.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/social_accounts'].get
  update:
    x-apievangelist-phrasing:
      intent: List my linked social accounts
      effect: read
      questions:
      - Which social media accounts are linked on my own profile?
      - What social links have I added to my account?
      instructions:
      - text: List the social accounts on my profile.
      - text: Show my own linked social media accounts, {per_page} per page.
        slots:
          per_page: query.per_page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/social_accounts'].post
  update:
    x-apievangelist-phrasing:
      intent: Add social accounts to my profile
      effect: write
      questions:
      - How do I add my social media links to my profile?
      - Can I add several social account URLs in one request?
      instructions:
      - text: Add {account_urls} as social accounts on my profile.
        slots:
          account_urls: requestBody.account_urls
      - text: Link the social profiles {account_urls} to my account.
        slots:
          account_urls: requestBody.account_urls
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/social_accounts'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove social accounts from my profile
      effect: destructive
      questions:
      - Can I remove a social media link from my profile?
      - Is it possible to delete multiple social accounts from my profile at once?
      instructions:
      - text: Remove {account_urls} from the social accounts on my profile.
        slots:
          account_urls: requestBody.account_urls
      - text: Unlink social profiles {account_urls} from my account.
        slots:
          account_urls: requestBody.account_urls
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/ssh_signing_keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List my SSH signing keys
      effect: read
      questions:
      - Which SSH keys have I registered for signing commits, as opposed to logging in?
      - What SSH signing keys are on my account right now?
      instructions:
      - text: List the SSH signing keys on my account.
      - text: Show my commit-signing SSH keys, page {page}.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/ssh_signing_keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an SSH signing key to my account
      effect: write
      questions:
      - How do I register an SSH key to sign my commits?
      - Can I name an SSH signing key when adding it?
      instructions:
      - text: Add {key} as an SSH signing key on my account.
        slots:
          key: requestBody.key
      - text: Register commit-signing SSH key {key} titled {title}.
        slots:
          key: requestBody.key
          title: requestBody.title
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/ssh_signing_keys/{ssh_signing_key_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of my SSH signing keys
      effect: read
      questions:
      - What are the details of a specific SSH signing key of mine?
      - Can I look up a commit-signing key by its id?
      instructions:
      - text: Get my SSH signing key {ssh_signing_key_id}.
        slots:
          ssh_signing_key_id: path.ssh_signing_key_id
      - text: Show details for commit-signing key {ssh_signing_key_id}.
        slots:
          ssh_signing_key_id: path.ssh_signing_key_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/ssh_signing_keys/{ssh_signing_key_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one of my SSH signing keys
      effect: destructive
      questions:
      - Can I remove an SSH key I only used for signing commits?
      - What's the way to retire an old commit-signing SSH key?
      instructions:
      - text: Delete my SSH signing key {ssh_signing_key_id}.
        slots:
          ssh_signing_key_id: path.ssh_signing_key_id
      - text: Remove commit-signing key {ssh_signing_key_id} from my account.
        slots:
          ssh_signing_key_id: path.ssh_signing_key_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List all users in signup order
      effect: read
      questions:
      - Can I page through every user and organization account in the order they signed up?
      - How do I continue listing all users after a certain user id?
      instructions:
      - text: List all user accounts in the order they signed up.
      - text: List every user account that signed up after user id {since}.
        slots:
          since: query.since
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a user's public profile
      effect: read
      questions:
      - What public information is available about someone's GitHub account?
      - Can I see a user's public profile, like their bio and company, by username?
      instructions:
      - text: Get the public profile of {username}.
        slots:
          username: path.username
      - text: 'Show me who {username} is: name, bio and public repos count.'
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/followers'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's followers
      effect: read
      questions:
      - Who follows a particular developer?
      - Can I see the follower list of someone else's account?
      instructions:
      - text: List the followers of {username}.
        slots:
          username: path.username
      - text: Show who follows {username}, {per_page} per page.
        slots:
          username: path.username
          per_page: query.per_page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/following'].get
  update:
    x-apievangelist-phrasing:
      intent: List who a user follows
      effect: read
      questions:
      - Which accounts does a given user follow?
      - Can I see the following list of someone else?
      instructions:
      - text: List the people {username} follows.
        slots:
          username: path.username
      - text: Show page {page} of accounts followed by {username}.
        slots:
          username: path.username
          page: query.page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/following/{target_user}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if one user follows another
      effect: read
      questions:
      - Does one particular user follow another particular user?
      - Can I test a follow relationship between two accounts that aren't mine?
      instructions:
      - text: Check whether {username} follows {target_user}.
        slots:
          username: path.username
          target_user: path.target_user
      - text: Tell me if user {username} is following {target_user}.
        slots:
          username: path.username
          target_user: path.target_user
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/gpg_keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List another user's GPG keys
      effect: read
      questions:
      - Which GPG keys has a given user published for commit verification?
      - Can I fetch someone else's GPG keys to verify their signatures?
      instructions:
      - text: List the GPG keys of {username}.
        slots:
          username: path.username
      - text: Show the public GPG keys published by {username}.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/hovercard'].get
  update:
    x-apievangelist-phrasing:
      intent: Get hovercard context about a user
      effect: read
      questions:
      - What's the hovercard context for a user in relation to a repository or pull request?
      - Can I find out how someone relates to a specific issue, organization or repo?
      instructions:
      - text: Get hovercard information for {username}.
        slots:
          username: path.username
      - text: Show how {username} relates to {subject_type} {subject_id}.
        slots:
          username: path.username
          subject_type: query.subject_type
          subject_id: query.subject_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List another user's verified SSH keys
      effect: read
      questions:
      - Which verified public SSH keys does a given user have?
      - Can I grab someone's SSH keys to grant them server access?
      instructions:
      - text: List the verified public SSH keys of {username}.
        slots:
          username: path.username
      - text: Show the SSH access keys published by user {username}.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/social_accounts'].get
  update:
    x-apievangelist-phrasing:
      intent: List another user's social accounts
      effect: read
      questions:
      - What social media accounts has a given developer linked?
      - Can I find someone's other social profiles from their username?
      instructions:
      - text: List the social accounts of {username}.
        slots:
          username: path.username
      - text: Show the social media profiles linked by {username}.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/ssh_signing_keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List another user's SSH signing keys
      effect: read
      questions:
      - Which SSH keys does a given user sign commits with?
      - Can I fetch another developer's SSH signing keys to verify their commits?
      instructions:
      - text: List the SSH signing keys of {username}.
        slots:
          username: path.username
      - text: Show commit-signing SSH keys published by {username}.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'