API Evangelist conversational phrasing for GitHub v3 REST Teams API

# 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 Teams API
  version: 1.0.0
extends: openapi/github-teams-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: 63
- target: $.paths['/orgs/{org}/external-group/{group_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up an external identity provider group
      effect: read
      questions:
      - Which members and teams are tied to one of our external IdP groups?
      - Can I see how a single identity provider group is being used in my GitHub org?
      instructions:
      - text: Show external group {group_id} in the {org} organization.
        slots:
          group_id: path.group_id
          org: path.org
      - text: List the external members and connected teams for IdP group {group_id} in {org}.
        slots:
          group_id: path.group_id
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/external-groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List external IdP groups in an organization
      effect: read
      questions:
      - What external identity provider groups are available to my organization?
      - Can I search our IdP groups by part of the group name?
      instructions:
      - text: List all external IdP groups available in {org}.
        slots:
          org: path.org
      - text: Find external groups in {org} whose name contains {display_name}.
        slots:
          org: path.org
          display_name: query.display_name
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams'].get
  update:
    x-apievangelist-phrasing:
      intent: List the teams in an organization
      effect: read
      questions:
      - What teams exist in my organization?
      - Which teams in the org can I actually see with my account?
      instructions:
      - text: List every team in the {org} organization.
        slots:
          org: path.org
      - text: Show the teams visible to me in {org}, {per_page} per page.
        slots:
          org: path.org
          per_page: query.per_page
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a team in an organization
      effect: write
      questions:
      - How do I create a new team in my GitHub organization?
      - Can I make a secret team that only its members and org owners can see?
      - Can a new team be nested under an existing parent team when I create it?
      instructions:
      - text: Create a team called {name} in {org}.
        slots:
          name: requestBody.name
          org: path.org
      - text: Create team {name} in {org} with privacy {privacy} and description {description}.
        slots:
          name: requestBody.name
          org: path.org
          privacy: requestBody.privacy
          description: requestBody.description
      - text: Create a new child team {name} in {org} under parent team {parent_team_id}.
        slots:
          name: requestBody.name
          org: path.org
          parent_team_id: requestBody.parent_team_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a team by its slug
      effect: read
      questions:
      - How can I look up a team's details from its slug?
      - What privacy setting and parent does a particular team have?
      instructions:
      - text: Get the team {team_slug} in {org}.
        slots:
          team_slug: path.team_slug
          org: path.org
      - text: Show me the details of the {team_slug} team in the {org} organization.
        slots:
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a team from an organization
      effect: destructive
      questions:
      - What happens to child teams when I delete a parent team in my org?
      - Who is allowed to delete a team in an organization?
      instructions:
      - text: Delete the team {team_slug} from {org}.
        slots:
          team_slug: path.team_slug
          org: path.org
      - text: Remove team {team_slug} entirely from the {org} organization.
        slots:
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a team's settings
      effect: write
      questions:
      - Can I rename an existing team or change its description?
      - How would I move an existing team under a different parent team?
      instructions:
      - text: Rename team {team_slug} in {org} to {name}.
        slots:
          team_slug: path.team_slug
          org: path.org
          name: requestBody.name
      - text: Change the privacy of team {team_slug} in {org} to {privacy}.
        slots:
          team_slug: path.team_slug
          org: path.org
          privacy: requestBody.privacy
      - text: Set parent team {parent_team_id} for the existing {team_slug} team in {org}.
        slots:
          parent_team_id: requestBody.parent_team_id
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/discussions'].get
  update:
    x-apievangelist-phrasing:
      intent: List discussions on a team's page
      effect: read
      questions:
      - What discussions have been posted on my team's page?
      - Can I see only the pinned discussions for a team?
      instructions:
      - text: List discussions on the {team_slug} team page in {org}.
        slots:
          team_slug: path.team_slug
          org: path.org
      - text: Show pinned discussions for team {team_slug} in {org}, sorted {direction}.
        slots:
          team_slug: path.team_slug
          org: path.org
          direction: query.direction
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/discussions'].post
  update:
    x-apievangelist-phrasing:
      intent: Post a new team discussion
      effect: write
      questions:
      - How can I start a discussion on my team's page?
      - Can I post a team discussion that only team members can see?
      instructions:
      - text: Post a discussion titled {title} saying {body} on the {team_slug} team in {org}.
        slots:
          title: requestBody.title
          body: requestBody.body
          team_slug: path.team_slug
          org: path.org
      - text: Start a private discussion {title} for team {team_slug} in {org} with text {body}.
        slots:
          title: requestBody.title
          team_slug: path.team_slug
          org: path.org
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one team discussion
      effect: read
      questions:
      - Can I pull up a single discussion post from a team page by its number?
      - What did a specific team discussion say?
      instructions:
      - text: Get discussion {discussion_number} on team {team_slug} in {org}.
        slots:
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
      - text: Open team discussion number {discussion_number} for {team_slug} in the {org} org.
        slots:
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a team discussion
      effect: destructive
      questions:
      - How do I remove a discussion post from my team's page?
      - Can a team discussion be deleted once it has been posted?
      instructions:
      - text: Delete discussion {discussion_number} from the {team_slug} team in {org}.
        slots:
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
      - text: Remove team discussion post {discussion_number} for {team_slug} in the {org} organization.
        slots:
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a team discussion's title or body
      effect: write
      questions:
      - Can I fix a typo in the title of a team discussion I already posted?
      - Is it possible to edit the body text of an existing team discussion?
      instructions:
      - text: Change the title of discussion {discussion_number} on team {team_slug} in {org} to {title}.
        slots:
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
          title: requestBody.title
      - text: Edit the body of team discussion {discussion_number} for {team_slug} in {org} to read {body}.
        slots:
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on a team discussion
      effect: read
      questions:
      - What replies have people left on a team discussion?
      - Can I read the comments on a team discussion oldest first?
      instructions:
      - text: List comments on discussion {discussion_number} for team {team_slug} in {org}.
        slots:
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
      - text: Show replies to team discussion {discussion_number} on {team_slug} in {org}, sorted {direction}.
        slots:
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
          direction: query.direction
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}/comments'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a team discussion
      effect: write
      questions:
      - How do I reply to a discussion on my team's page?
      - Does adding a comment to a team discussion notify people?
      instructions:
      - text: Comment {body} on discussion {discussion_number} for team {team_slug} in {org}.
        slots:
          body: requestBody.body
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
      - text: Reply to team discussion {discussion_number} on {team_slug} in {org} with {body}.
        slots:
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}/comments/{comment_number}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one comment on a team discussion
      effect: read
      questions:
      - Can I fetch a single reply on a team discussion by its comment number?
      - What exactly did one specific comment on our team discussion say?
      instructions:
      - text: Fetch the single reply {comment_number} on discussion {discussion_number} for team {team_slug} in {org}.
        slots:
          comment_number: path.comment_number
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
      - text: Show reply {comment_number} in team discussion {discussion_number} of {team_slug}, {org}.
        slots:
          comment_number: path.comment_number
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}/comments/{comment_number}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a comment on a team discussion
      effect: destructive
      questions:
      - How can I remove a reply someone posted on a team discussion?
      - Is deleting a team discussion comment permanent?
      instructions:
      - text: Delete comment {comment_number} from discussion {discussion_number} on team {team_slug} in {org}.
        slots:
          comment_number: path.comment_number
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
      - text: Remove reply {comment_number} under team discussion {discussion_number} for {team_slug} in the {org} org.
        slots:
          comment_number: path.comment_number
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}/comments/{comment_number}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a comment on a team discussion
      effect: write
      questions:
      - Can I edit a reply I already left on a team discussion?
      - Is there a way to correct the text of an existing team discussion comment?
      instructions:
      - text: Change comment {comment_number} on discussion {discussion_number} for team {team_slug} in {org} to {body}.
        slots:
          comment_number: path.comment_number
          discussion_number: path.discussion_number
          team_slug: path.team_slug
          org: path.org
          body: requestBody.body
      - text: Rewrite my reply {comment_number} in {team_slug}'s discussion {discussion_number} ({org}) as {body}.
        slots:
          comment_number: path.comment_number
          team_slug: path.team_slug
          discussion_number: path.discussion_number
          org: path.org
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/external-groups'].get
  update:
    x-apievangelist-phrasing:
      intent: See which external group is linked to a team
      effect: read
      questions:
      - Which identity provider group is connected to this team?
      - Is my team's membership being managed by an external IdP group?
      instructions:
      - text: Show the external group linked to team {team_slug} in {org}.
        slots:
          team_slug: path.team_slug
          org: path.org
      - text: Check whether team {team_slug} in {org} is connected to an IdP group.
        slots:
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/external-groups'].delete
  update:
    x-apievangelist-phrasing:
      intent: Disconnect an external group from a team
      effect: destructive
      questions:
      - How do I stop an IdP group from managing a team's membership?
      - Can I break the link between a team and its external identity group?
      instructions:
      - text: Unlink the external IdP group from team {team_slug} in {org}.
        slots:
          team_slug: path.team_slug
          org: path.org
      - text: Remove the identity provider group connection on the {team_slug} team in {org}.
        slots:
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/external-groups'].patch
  update:
    x-apievangelist-phrasing:
      intent: Connect an external IdP group to a team
      effect: write
      questions:
      - Can I manage a team's members through an external identity provider group?
      - How many external groups can be linked to one team?
      instructions:
      - text: Link external group {group_id} to team {team_slug} in {org}.
        slots:
          group_id: requestBody.group_id
          team_slug: path.team_slug
          org: path.org
      - text: Connect IdP group {group_id} so it manages membership of {team_slug} in the {org} organization.
        slots:
          group_id: requestBody.group_id
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List the members of a team
      effect: read
      questions:
      - Who is on a particular team in my org?
      - Can I list only the maintainers of a team?
      - Do child team members show up when I list a team's members?
      instructions:
      - text: List the members of team {team_slug} in {org}.
        slots:
          team_slug: path.team_slug
          org: path.org
      - text: Show members of {team_slug} in {org} who have the {role} role.
        slots:
          team_slug: path.team_slug
          org: path.org
          role: query.role
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/memberships/{username}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a user's membership in a team
      effect: read
      questions:
      - Is a specific person a member or maintainer of my team?
      - Can I tell whether someone's team membership is still pending?
      instructions:
      - text: Check {username}'s membership in team {team_slug} in {org}.
        slots:
          username: path.username
          team_slug: path.team_slug
          org: path.org
      - text: Get the team role and membership state of {username} on {team_slug} in the {org} org.
        slots:
          username: path.username
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/memberships/{username}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add a user to a team or change their role
      effect: write
      questions:
      - How do I add someone in my org to a team?
      - Can I promote a team member to maintainer?
      - Why would adding a team member fail when team sync with our IdP is on?
      instructions:
      - text: Add {username} to team {team_slug} in {org}.
        slots:
          username: path.username
          team_slug: path.team_slug
          org: path.org
      - text: Set {username}'s role on team {team_slug} in {org} to {role}.
        slots:
          username: path.username
          team_slug: path.team_slug
          org: path.org
          role: requestBody.role
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/memberships/{username}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from a team
      effect: destructive
      questions:
      - How can I take someone off a team without removing them from the org?
      - What permission do I need to remove a person from a team?
      instructions:
      - text: Remove {username} from team {team_slug} in {org}.
        slots:
          username: path.username
          team_slug: path.team_slug
          org: path.org
      - text: Take user {username} off the {team_slug} team in the {org} organization.
        slots:
          username: path.username
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/projects'].get
  update:
    x-apievangelist-phrasing:
      intent: List a team's projects
      effect: read
      questions:
      - Which organization projects does a team have access to?
      - What projects are assigned to my team?
      instructions:
      - text: List the projects for team {team_slug} in {org}.
        slots:
          team_slug: path.team_slug
          org: path.org
      - text: Show every org project the {team_slug} team in {org} can reach.
        slots:
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/projects/{project_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a team's permission on a project
      effect: read
      questions:
      - Does my team have read, write or admin access to a given project?
      - Are project permissions inherited from a parent team counted?
      instructions:
      - text: Check team {team_slug}'s permission on project {project_id} in {org}.
        slots:
          team_slug: path.team_slug
          project_id: path.project_id
          org: path.org
      - text: Tell me what access {team_slug} in {org} has to project {project_id}.
        slots:
          team_slug: path.team_slug
          org: path.org
          project_id: path.project_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/projects/{project_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Grant a team access to a project
      effect: write
      questions:
      - How do I give a team access to an organization project?
      - Can I change a team's permission on a project from read to admin?
      instructions:
      - text: Add project {project_id} to team {team_slug} in {org}.
        slots:
          project_id: path.project_id
          team_slug: path.team_slug
          org: path.org
      - text: Grant team {team_slug} in {org} {permission} permission on project {project_id}.
        slots:
          team_slug: path.team_slug
          org: path.org
          permission: requestBody.permission
          project_id: path.project_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/projects/{project_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a project from a team
      effect: destructive
      questions:
      - How can I take a project away from a team?
      - Does removing a project from a team delete the project?
      instructions:
      - text: Remove project {project_id} from team {team_slug} in {org}.
        slots:
          project_id: path.project_id
          team_slug: path.team_slug
          org: path.org
      - text: Revoke the {team_slug} team's access to project {project_id} in the {org} org.
        slots:
          team_slug: path.team_slug
          project_id: path.project_id
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/repos'].get
  update:
    x-apievangelist-phrasing:
      intent: List a team's repositories
      effect: read
      questions:
      - Which repositories does my team have access to?
      - What repos are assigned to a team in the org?
      instructions:
      - text: List the repositories for team {team_slug} in {org}.
        slots:
          team_slug: path.team_slug
          org: path.org
      - text: Show every repo the {team_slug} team in {org} can access.
        slots:
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a team's permission on a repository
      effect: read
      questions:
      - Does a team have push or admin rights on a specific repo?
      - What level of access does my team have to a repository, counting parent teams?
      instructions:
      - text: Check what repository role team {team_slug} holds on the {owner}/{repo} repo in {org}.
        slots:
          team_slug: path.team_slug
          owner: path.owner
          repo: path.repo
          org: path.org
      - text: Tell me whether {team_slug} in {org} can push to repository {owner}/{repo}.
        slots:
          team_slug: path.team_slug
          org: path.org
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}'].put
  update:
    x-apievangelist-phrasing:
      intent: Grant a team access to a repository
      effect: write
      questions:
      - How do I give a team access to a repository?
      - Can I set a team to triage or maintain on a repo instead of full admin?
      - Why do I get a 422 when adding a repo to a team?
      instructions:
      - text: Add repository {owner}/{repo} to team {team_slug} in {org}.
        slots:
          owner: path.owner
          repo: path.repo
          team_slug: path.team_slug
          org: path.org
      - text: Give team {team_slug} in {org} {permission} access to {owner}/{repo}.
        slots:
          team_slug: path.team_slug
          org: path.org
          permission: requestBody.permission
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a repository from a team
      effect: destructive
      questions:
      - How can I stop a team from accessing a repository?
      - Does taking a repo away from a team delete the repo itself?
      instructions:
      - text: Detach the {owner}/{repo} repository from team {team_slug} in {org}.
        slots:
          owner: path.owner
          repo: path.repo
          team_slug: path.team_slug
          org: path.org
      - text: Revoke the {team_slug} team's access to repository {owner}/{repo} in the {org} org.
        slots:
          team_slug: path.team_slug
          owner: path.owner
          repo: path.repo
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/orgs/{org}/teams/{team_slug}/teams'].get
  update:
    x-apievangelist-phrasing:
      intent: List a team's child teams
      effect: read
      questions:
      - Which teams are nested under a given parent team?
      - What sub-teams does my team have?
      instructions:
      - text: List the child teams of {team_slug} in {org}.
        slots:
          team_slug: path.team_slug
          org: path.org
      - text: Show the nested sub-teams beneath team {team_slug} in the {org} org.
        slots:
          team_slug: path.team_slug
          org: path.org
      method: generated
      generated: '2026-09-24'
- target: $.paths['/teams/{team_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a team by numeric ID (legacy)
      effect: read
      questions:
      - Can I still fetch a team using only its numeric team ID?
      - Is the old get-team-by-ID route deprecated?
      instructions:
      - text: Using the legacy team ID route, get team {team_id}.
        slots:
          team_id: path.team_id
      - text: Fetch team details for numeric ID {team_id} via the deprecated endpoint.
        slots:
          team_id: path.team_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/teams/{team_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a team by numeric ID (legacy)
      effect: destructive
      questions:
      - Can I delete a team when all I have is its numeric ID?
      - Is deleting a team through the old ID-based route still supported?
      instructions:
      - text: Using the legacy team ID route, delete team {team_id}.
        slots:
          team_id: path.team_id
      - text: Delete numeric team ID {team_id} via the deprecated endpoint.
        slots:
          team_id: path.team_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/teams/{team_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a team by numeric ID (legacy)
      effect: write
      questions:
      - Can I rename a team through the old team ID endpoint?
      - Does the deprecated team update route require the name every time?
      instructions:
      - text: Using the legacy team ID route, rename team {team_id} to {name}.
        slots:
          team_id: path.team_id
          name: requestBody.name
      - text: Via the deprecated endpoint, set numeric team {team_id} name {name} and privacy {privacy}.
        slots:
          team_id: path.team_id
          name: requestBody.name
          privacy: requestBody.privacy
      method: generated
      generated: '2026-09-24'
- target: $.paths['/teams/{team_id}/discussions'].get
  update:
    x-apievangelist-phrasing:
      intent: List team discussions by team ID (legacy)
      effect: read
      questions:
      - Can I list a team's discussions using its numeric ID instead of the slug?
      - Is the ID-based team discussion list going away?
      instructions:
      - text: Using the legacy team ID route, list discussions for team {team_id}.
        slots:
          team_id: path.team_id
      - text: Via the deprecated endpoint, show numeric team {team_id} discussions sorted {direction}.
        slots:
          team_id: path.team_id
          direction: query.direction
      method: generated
      generated: '2026-09-24'
- target: $.paths['/teams/{team_id}/discussions'].post
  update:
    x-apievangelist-phrasing:
      intent: Post a team discussion by team ID (legacy)
      effect: write
      questions:
      - Can I start a team discussion when I only know the numeric team ID?
      - Does the old ID-based discussion post route still trigger notifications?
      instructions:
      - text: Using the legacy team ID route, post discussion {title} with body {body} to team {team_id}.
        slots:
          title: requestBody.title
          body: requestBody.body
          team_id: path.team_id
      - text: 'Via the deprecated endpoint, open a new thread {title} on numeric team {team_id}: {body}.'
        slots:
          title: requestBody.title
          team_id: path.team_id
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/teams/{team_id}/discussions/{discussion_number}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a team discussion by team ID (legacy)
      effect: read
      questions:
      - Can I read one team discussion using the numeric team ID route?
      - Is fetching a single discussion by team ID deprecated?
      instructions:
      - text: Using the legacy team ID route, get discussion {discussion_number} of team {team_id}.
        slots:
          discussion_number: path.discussion_number
          team_id: path.team_id
      - text: Via the deprecated endpoint, open thread {discussion_number} on numeric team {team_id}.
        slots:
          discussion_number: path.discussion_number
          team_id: path.team_id
      method: generated
      generated: '2026-09-24'


# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/overlays/github-teams-api-phrasing-overlay.yaml