# 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 Activity API
  version: 1.0.0
extends: openapi/github-activity-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: 31
- target: $.paths['/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List recent public events across the server
      effect: read
      questions:
      - What public activity is happening across the whole GitHub instance right now?
      - Can I see a global stream of recent public events from every user and repo?
      instructions:
      - text: List the latest public events across the entire server.
      - text: Show me the global public activity stream.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/feeds'].get
  update:
    x-apievangelist-phrasing:
      intent: List the Atom feeds available to me
      effect: read
      questions:
      - Which Atom timeline feeds can I subscribe to as the signed-in user?
      - Where do I find the URL of my private activity feed for a feed reader?
      instructions:
      - text: List the Atom feed URLs available to my account.
      - text: Get my timeline feed links for a feed reader.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/networks/{owner}/{repo}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List public events for a repository's fork network
      effect: read
      questions:
      - What public activity is happening across a repository and all of its forks?
      - Can I see events from the whole fork network of a project, not just the main repo?
      instructions:
      - text: List public events across the fork network of {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Show activity from {repo} by {owner} and every fork of it.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/notifications'].get
  update:
    x-apievangelist-phrasing:
      intent: List my notifications
      effect: read
      questions:
      - What unread notifications do I have across all my repositories?
      - Can I list only notifications for threads where I'm directly participating or mentioned?
      - Which notifications came in since yesterday morning?
      instructions:
      - text: List my unread notifications from every repository.
      - text: Show my notifications updated after {since}.
        slots:
          since: query.since
      - text: List all my notifications, including read ones, with all set to {all}.
        slots:
          all: query.all
      method: generated
      generated: '2026-09-24'
- target: $.paths['/notifications'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark all my notifications as read
      effect: write
      questions:
      - How do I clear every notification in my inbox at once?
      - Can I mark notifications read only up to a certain time, leaving newer ones unread?
      instructions:
      - text: Mark all my notifications across every repository as read.
      - text: Mark my notifications as read up to {last_read_at}.
        slots:
          last_read_at: requestBody.last_read_at
      method: generated
      generated: '2026-09-24'
- target: $.paths['/notifications/threads/{thread_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one notification thread
      effect: read
      questions:
      - What is a particular notification thread about and why did I get it?
      - Can I look up the details of one notification by its thread ID?
      instructions:
      - text: Show notification thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Get the subject and reason for notification {thread_id}.
        slots:
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/notifications/threads/{thread_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Mark one notification thread as read
      effect: write
      questions:
      - Can I mark just a single notification as read without clearing the rest?
      - Is there a way to dismiss one notification thread as read?
      instructions:
      - text: Mark notification thread {thread_id} as read.
        slots:
          thread_id: path.thread_id
      - text: Dismiss thread {thread_id} as read, leaving my other notifications alone.
        slots:
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/notifications/threads/{thread_id}/subscription'].get
  update:
    x-apievangelist-phrasing:
      intent: Check my subscription to a notification thread
      effect: read
      questions:
      - Am I subscribed to a given notification thread, or have I ignored it?
      - Why do I keep getting updates on this thread — am I subscribed?
      instructions:
      - text: Check my subscription status for thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Tell me whether I'm ignoring notification thread {thread_id}.
        slots:
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/notifications/threads/{thread_id}/subscription'].put
  update:
    x-apievangelist-phrasing:
      intent: Subscribe to or ignore a notification thread
      effect: write
      questions:
      - Can I mute a noisy thread until someone mentions me again?
      - How do I start getting notifications on a thread I'm not currently following?
      instructions:
      - text: Ignore future notifications on thread {thread_id} by setting ignored to {ignored}.
        slots:
          thread_id: path.thread_id
          ignored: requestBody.ignored
      - text: Subscribe me to notification thread {thread_id}.
        slots:
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/notifications/threads/{thread_id}/subscription'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unsubscribe from a notification thread
      effect: destructive
      questions:
      - How do I stop following a thread entirely rather than just muting it?
      - Can I remove my subscription to one conversation so it reverts to my repo watch setting?
      instructions:
      - text: Delete my subscription to thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Unsubscribe me completely from notification thread {thread_id}.
        slots:
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's public events
      effect: read
      questions:
      - What public activity has an organization had recently?
      - Can I see the public event feed for a company's GitHub org?
      instructions:
      - text: List public events for organization {org}.
        slots:
          org: path.org
      - text: Show the recent public activity of {org}.
        slots:
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List events for a single repository
      effect: read
      questions:
      - What has happened recently in one repository, like pushes, issues and pull requests?
      - Can I get the activity feed of a single repo without its forks?
      instructions:
      - text: List recent events for repository {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Show the activity feed of {repo} owned by {owner}, excluding forks.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/notifications'].get
  update:
    x-apievangelist-phrasing:
      intent: List my notifications for one repository
      effect: read
      questions:
      - What notifications do I have for just one repository?
      - Can I see only the notifications from a single repo where I'm participating?
      instructions:
      - text: List my notifications for {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Show my notifications in {owner}/{repo} since {since}.
        slots:
          owner: path.owner
          repo: path.repo
          since: query.since
      - text: List repo {owner}/{repo} notifications where participating is {participating}.
        slots:
          owner: path.owner
          repo: path.repo
          participating: query.participating
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/notifications'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark all notifications in one repository as read
      effect: write
      questions:
      - Can I clear every notification from one repo without touching my other repos?
      - Is it possible to mark a repository's notifications read only up to a set time?
      instructions:
      - text: Mark all my notifications in {owner}/{repo} as read.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Mark repo {owner}/{repo} notifications read up to {last_read_at}.
        slots:
          owner: path.owner
          repo: path.repo
          last_read_at: requestBody.last_read_at
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/stargazers'].get
  update:
    x-apievangelist-phrasing:
      intent: List who starred a repository
      effect: read
      questions:
      - Who has starred a particular repository?
      - Can I get the list of stargazers for a project?
      instructions:
      - text: List the stargazers of {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Show everyone who starred {repo} by {owner}.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/subscribers'].get
  update:
    x-apievangelist-phrasing:
      intent: List who watches a repository
      effect: read
      questions:
      - Which users are watching a repository for notifications?
      - Who is subscribed to updates from a given repo?
      instructions:
      - text: List the watchers of {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Show the users subscribed to notifications for {repo} owned by {owner}.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/subscription'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether I'm watching a repository
      effect: read
      questions:
      - Am I watching a given repository, or have I set it to ignore?
      - What's my notification setting on this repo?
      instructions:
      - text: Check my watch subscription for {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Tell me if I'm ignoring notifications from {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/subscription'].put
  update:
    x-apievangelist-phrasing:
      intent: Watch or ignore a repository
      effect: write
      questions:
      - How do I start watching a repository so I get all its notifications?
      - Can I block every notification from a noisy repo without unwatching it?
      instructions:
      - text: Watch {owner}/{repo} by setting subscribed to {subscribed}.
        slots:
          owner: path.owner
          repo: path.repo
          subscribed: requestBody.subscribed
      - text: Ignore all notifications from {owner}/{repo} with ignored set to {ignored}.
        slots:
          owner: path.owner
          repo: path.repo
          ignored: requestBody.ignored
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/subscription'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop watching a repository
      effect: destructive
      questions:
      - What's the way to stop watching a repository completely?
      - Can I delete my watch subscription on a repo instead of just ignoring it?
      instructions:
      - text: Stop watching {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Remove my repository subscription for {repo} owned by {owner}.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/starred'].get
  update:
    x-apievangelist-phrasing:
      intent: List the repositories I've starred
      effect: read
      questions:
      - Which repositories have I starred?
      - Can I sort my starred repos by when I starred them?
      instructions:
      - text: List the repositories I've starred.
      - text: Show my starred repos sorted by {sort} in {direction} order.
        slots:
          sort: query.sort
          direction: query.direction
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/starred/{owner}/{repo}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether I've starred a repository
      effect: read
      questions:
      - Have I already starred a particular repository?
      - Is this repo in my stars?
      instructions:
      - text: Check whether I've starred {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Confirm {repo} by {owner} is in my stars.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/starred/{owner}/{repo}'].put
  update:
    x-apievangelist-phrasing:
      intent: Star a repository
      effect: write
      questions:
      - Can I star a repository through the API?
      - How do I bookmark a project by starring it?
      instructions:
      - text: Star {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Add {repo} from {owner} to my starred repositories.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/starred/{owner}/{repo}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unstar a repository
      effect: destructive
      questions:
      - How can I remove a star I gave to a repository?
      - Can I unstar a project I no longer follow?
      instructions:
      - text: Unstar {owner}/{repo}.
        slots:
          owner: path.owner
          repo: path.repo
      - text: Remove {repo} from {owner} from my starred list.
        slots:
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/user/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the repositories I'm watching
      effect: read
      questions:
      - Which repositories am I currently watching?
      - What repos am I subscribed to for notifications?
      instructions:
      - text: List the repositories I'm watching.
      - text: Show every repo my account is subscribed to.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List events performed by a user, private included
      effect: read
      questions:
      - What has a user been doing lately, including private events if I'm signed in as them?
      - Can I see my own full activity history, not just the public part?
      instructions:
      - text: List the events performed by {username}, including private ones if I'm that user.
        slots:
          username: path.username
      - text: Show my own recent activity as {username}.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/events/orgs/{org}'].get
  update:
    x-apievangelist-phrasing:
      intent: List my private organization dashboard events
      effect: read
      questions:
      - What does my organization dashboard feed show, including private activity?
      - Can I see private events inside an org I belong to?
      instructions:
      - text: List the organization dashboard events for {username} in {org}.
        slots:
          username: path.username
          org: path.org
      - text: Show private activity from {org} as seen by {username}.
        slots:
          username: path.username
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/events/public'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's public events only
      effect: read
      questions:
      - What public activity has a specific GitHub user had?
      - Can I see only the public events someone performed, never their private ones?
      instructions:
      - text: List only the public events performed by {username}.
        slots:
          username: path.username
      - text: Show the public activity feed of user {username}.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/received_events'].get
  update:
    x-apievangelist-phrasing:
      intent: List events a user received from follows and watches
      effect: read
      questions:
      - What events show up in a user's feed from the people they follow and repos they watch?
      - Can I see my received events, private ones included?
      instructions:
      - text: List the events {username} received from followed users and watched repos.
        slots:
          username: path.username
      - text: Show the incoming activity feed for {username}, including private events.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/received_events/public'].get
  update:
    x-apievangelist-phrasing:
      intent: List public events a user received
      effect: read
      questions:
      - Which public events landed in a user's feed from the accounts and repos they follow?
      - Can I view someone's received feed restricted to public events?
      instructions:
      - text: List only the public events received by {username}.
        slots:
          username: path.username
      - text: Show the public part of the feed {username} receives.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/starred'].get
  update:
    x-apievangelist-phrasing:
      intent: List repositories another user has starred
      effect: read
      questions:
      - Which repositories has a specific GitHub user starred?
      - Can I sort another person's stars by most recently starred?
      instructions:
      - text: List the repositories {username} has starred.
        slots:
          username: path.username
      - text: Show repos starred by {username}, sorted by {sort}.
        slots:
          username: path.username
          sort: query.sort
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List repositories another user is watching
      effect: read
      questions:
      - What repositories is a given user watching?
      - Which repos does someone else follow for notifications?
      instructions:
      - text: List the repositories {username} is watching.
        slots:
          username: path.username
      - text: Show the repos {username} subscribes to.
        slots:
          username: path.username
      method: generated
      generated: '2026-09-24'