The GitHub Teams API lets you programmatically manage organization teams and the access they grant. With it, you can create, update, and delete teams; organize parent/child team hierarchies; add or remove members and maintainers; send and manage invitations; and list or audit team membership. It also lets you grant, adjust, or revoke a teams permissions to repositories (and, where applicable, projects), enabling consistent, leastprivilege access control at scale.
openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Teams API
description: >-
The GitHub Teams API allows developers to programmatically create and manage
teams within GitHub organizations, which are groups of organization members
that reflect your company or group's structure and provide cascading access
permissions to repositories. Through these REST API endpoints, you can
create and delete teams, add or remove team members and maintainers, manage
team repositories and their permission levels, organize teams into
hierarchical structures with parent and child teams, configure team settings
like privacy levels and notifications, and access team discussions. This API
is essential for automating team management workflows, synchronizing GitHub
team structures with external HR or directory systems, building custom
administrative dashboards, and maintaining consistent access control as your
organization scales.
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
tags:
- name: Access
- name: Add
- name: Authenticated
- name: Between
- name: Branches
- name: Checks
- name: Child
- name: Comments
- name: Connection
- name: Create
- name: Delete
- name: Discussions
- name: External
- name: Get
- name: Groups
- name: Ldap
- name: Legacy
- name: Lists
- name: Manager
- name: Mapping
- name: Member
- name: Members
- name: Memberships
- name: Name
- name: Permissions
- name: Projects
- name: Protected
- name: Reactions
- name: Remove
- name: Repositories
- name: Restrictions
- name: Security
- name: Sets
- name: Sync
- name: Teams
- name: Update
- name: Users
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
paths:
/admin/ldap/teams/{team_id}/mapping:
patch:
summary: GitHub Update Ldap Mapping for Team
description: >-
Updates the [distinguished name](https://www.ldap.com/ldap-dns-and-rdns)
(DN) of the LDAP entry to map to a team. [LDAP
synchronization](https://docs.github.com/[email protected]/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#enabling-ldap-sync)
must be enabled to map LDAP entries to a team. Use the [Create a
team](https://docs.github.com/[email protected]/rest/teams/teams/#create-a-team)
endpoint to create a team with LDAP mapping.
operationId: updateLdapMappingForTeam
tags:
- Ldap
- Mapping
- Teams
- Update
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/ldap#update-ldap-mapping-for-a-team
parameters:
- $ref: '#/components/parameters/team-id'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/ldap-mapping-team'
examples:
default:
$ref: '#/components/examples/ldap-mapping-team'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ldap_dn:
type: string
description: >-
The [distinguished
name](https://www.ldap.com/ldap-dns-and-rdns) (DN) of the
LDAP entry to map to a team.
required:
- ldap_dn
examples:
default:
value:
ldap_dn: cn=Enterprise Ops,ou=teams,dc=github,dc=com
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: ldap
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/ldap/teams/{team_id}/sync:
post:
summary: GitHub Sync Ldap Mapping for Team
description: >-
Note that this API call does not automatically initiate an LDAP sync.
Rather, if a `201` is returned, the sync job is queued successfully, and
is performed when the instance is ready.
operationId: syncLdapMappingForTeam
tags:
- Ldap
- Mapping
- Sync
- Teams
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/ldap#sync-ldap-mapping-for-a-team
parameters:
- $ref: '#/components/parameters/team-id'
responses:
'201':
description: Response
content:
application/json:
schema:
type: object
properties:
status:
type: string
examples:
default:
value:
status: queued
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: ldap
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/security-managers/teams/{team_slug}:
put:
summary: GitHub Add Security Manager Team
description: >-
Adds a team as a security manager for an organization. For more
information, see "[Managing security for an
organization](https://docs.github.com/[email protected]/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)
for an organization."
The authenticated user must be an administrator for the organization to
use this endpoint.
OAuth app tokens and personal access tokens (classic) need the
`write:org` scope to use this endpoint.
tags:
- Add
- Manager
- Security
- Teams
operationId: addSecurityManagerTeam
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/orgs/security-managers#add-a-security-manager-team
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
responses:
'204':
description: Response
'409':
description: >-
The organization has reached the maximum number of security manager
teams.
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
previews: []
category: orgs
subcategory: security-managers
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove Security Manager Team
description: >-
Removes the security manager role from a team for an organization. For
more information, see "[Managing security managers in your
organization](https://docs.github.com/[email protected]/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)
team from an organization."
The authenticated user must be an administrator for the organization to
use this endpoint.
OAuth app tokens and personal access tokens (classic) need the
`admin:org` scope to use this endpoint.
tags:
- Manager
- Remove
- Security
- Teams
operationId: removeSecurityManagerTeam
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/orgs/security-managers#remove-a-security-manager-team
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
responses:
'204':
description: Response
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
previews: []
category: orgs
subcategory: security-managers
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/teams:
get:
summary: GitHub List Teams
description: >-
The List Teams operation retrieves all teams within a specified GitHub
organization using a GET request to the /orgs/{org}/teams endpoint. This
API call returns an array of team objects containing details such as
team name, ID, slug, description, privacy level, and permission
settings. Authentication is required with appropriate OAuth scopes or
personal access tokens that grant read access to the organization. The
response can be paginated using standard GitHub pagination parameters,
and the results may be filtered based on the authenticated user's
permissions within the organization. This endpoint is commonly used by
organization administrators and applications that need to enumerate
teams for management, reporting, or integration purposes.
tags:
- Lists
- Teams
operationId: listTeams
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/teams/teams#list-teams
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/team'
examples:
default:
$ref: '#/components/examples/team-items'
headers:
Link:
$ref: '#/components/headers/link'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: teams
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create Team
description: >-
To create a team, the authenticated user must be a member or owner of
`{org}`. By default, organization members can create teams. Organization
owners can limit team creation to organization owners. For more
information, see "[Setting team creation
permissions](https://docs.github.com/[email protected]/articles/setting-team-creation-permissions-in-your-organization)."
When you create a new team, you automatically become a team maintainer
without explicitly adding yourself to the optional array of
`maintainers`. For more information, see "[About
teams](https://docs.github.com/[email protected]/github/setting-up-and-managing-organizations-and-teams/about-teams)".
tags:
- Create
- Teams
operationId: createTeam
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/teams/teams#create-a-team
parameters:
- $ref: '#/components/parameters/org'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the team.
description:
type: string
description: The description of the team.
maintainers:
type: array
description: >-
List GitHub IDs for organization members who will become
team maintainers.
items:
type: string
repo_names:
type: array
description: >-
The full name (e.g., "organization-name/repository-name") of
repositories to add the team to.
items:
type: string
privacy:
type: string
description: >-
The level of privacy this team should have. The options
are:
**For a non-nested team:**
* `secret` - only visible to organization owners and members of this team.
* `closed` - visible to all members of this organization.
Default: `secret`
**For a parent or child team:**
* `closed` - visible to all members of this organization.
Default for child team: `closed`
enum:
- secret
- closed
permission:
type: string
description: >-
**Deprecated**. The permission that new repositories will be
added to the team with when none is specified.
enum:
- pull
- push
default: pull
parent_team_id:
type: integer
description: The ID of a team to set as the parent team.
ldap_dn:
type: string
description: >-
The [distinguished
name](https://www.ldap.com/ldap-dns-and-rdns) (DN) of the
LDAP entry to map to a team. LDAP synchronization must be
enabled to map LDAP entries to a team. Use the "[Update LDAP
mapping for a
team](https://docs.github.com/[email protected]/rest/enterprise-admin/ldap#update-ldap-mapping-for-a-team)"
endpoint to change the LDAP DN. For more information, see
"[Using
LDAP](https://docs.github.com/[email protected]/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-ldap#enabling-ldap-sync)."
required:
- name
examples:
default:
value:
name: Justice League
description: A great team
permission: push
privacy: closed
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/team-full'
examples:
default:
$ref: '#/components/examples/team-full'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: teams
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/teams/{team_slug}:
get:
summary: GitHub Get Team by Name
description: >-
Gets a team using the team's `slug`. To create the `slug`, GitHub
Enterprise Server replaces special characters in the `name` string,
changes all words to lowercase, and replaces spaces with a `-`
separator. For example, `"My TEam Näme"` would become `my-team-name`.
**Note:** You can also specify a team by `org_id` and `team_id` using
the route `GET /organizations/{org_id}/team/{team_id}`.
tags:
- Get
- Name
- Teams
operationId: getTeamByName
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/teams/teams#get-a-team-by-name
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/team-full'
examples:
default:
$ref: '#/components/examples/team-full'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: teams
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update Team
description: >-
To edit a team, the authenticated user must either be an organization
owner or a team maintainer.
**Note:** You can also specify a team by `org_id` and `team_id` using
the route `PATCH /organizations/{org_id}/team/{team_id}`.
tags:
- Teams
- Update
operationId: updateTeam
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/teams/teams#update-a-team
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the team.
description:
type: string
description: The description of the team.
privacy:
type: string
description: >-
The level of privacy this team should have. Editing teams
without specifying this parameter leaves `privacy` intact.
When a team is nested, the `privacy` for parent teams cannot
be `secret`. The options are:
**For a non-nested team:**
* `secret` - only visible to organization owners and members of this team.
* `closed` - visible to all members of this organization.
**For a parent or child team:**
* `closed` - visible to all members of this organization.
enum:
- secret
- closed
permission:
type: string
description: >-
**Deprecated**. The permission that new repositories will be
added to the team with when none is specified.
enum:
- pull
- push
- admin
default: pull
parent_team_id:
type: integer
description: The ID of a team to set as the parent team.
nullable: true
examples:
default:
value:
name: new team name
description: new team description
privacy: closed
responses:
'200':
description: Response when the updated information already exists
content:
application/json:
schema:
$ref: '#/components/schemas/team-full'
examples:
default:
$ref: '#/components/examples/team-full'
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/team-full'
examples:
default:
$ref: '#/components/examples/team-full'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: teams
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete Team
description: >-
To delete a team, the authenticated user must be an organization owner
or team maintainer.
If you are an organization owner, deleting a parent team will delete all
of its child teams as well.
**Note:** You can also specify a team by `org_id` and `team_id` using
the route `DELETE /organizations/{org_id}/team/{team_id}`.
tags:
- Delete
- Teams
operationId: deleteTeam
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/teams/teams#delete-a-team
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
responses:
'204':
description: Response
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: teams
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/teams/{team_slug}/discussions:
get:
summary: GitHub List Discussions
description: >-
List all discussions on a team's page.
**Note:** You can also specify a team by `org_id` and `team_id` using
the route `GET /organizations/{org_id}/team/{team_id}/discussions`.
OAuth app tokens and personal access tokens (classic) need the
`read:discussion` scope to use this endpoint.
tags:
- Discussions
- Lists
operationId: listDiscussions
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/teams/discussions#list-discussions
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
- $ref: '#/components/parameters/direction'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- name: pinned
in: query
required: false
description: Pinned discussions only filter
schema:
type: string
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/team-discussion'
examples:
default:
$ref: '#/components/examples/team-discussion-items'
headers:
Link:
$ref: '#/components/headers/link'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: discussions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create Discussion
description: >-
Creates a new discussion post on a team's page.
This endpoint triggers
[notifications](https://docs.github.com/[email protected]/github/managing-subscriptions-and-notifications-on-github/about-notifications).
Creating content too quickly using this endpoint may result in secondary
rate limiting. For more information, see "[Rate limits for the
API](https://docs.github.com/[email protected]/rest/overview/rate-limits-for-the-rest-api#about-secondary-rate-limits)"
and "[Best practices for using the REST
API](https://docs.github.com/[email protected]/rest/guides/best-practices-for-using-the-rest-api)."
**Note:** You can also specify a team by `org_id` and `team_id` using
the route `POST /organizations/{org_id}/team/{team_id}/discussions`.
OAuth app tokens and personal access tokens (classic) need the
`write:discussion` scope to use this endpoint.
tags:
- Create
- Discussions
operationId: createDiscussion
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/teams/discussions#create-a-discussion
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: The discussion post's title.
body:
type: string
description: The discussion post's body text.
private:
type: boolean
description: >-
Private posts are only visible to team members, organization
owners, and team maintainers. Public posts are visible to
all members of the organization. Set to `true` to create a
private post.
default: false
required:
- title
- body
examples:
default:
value:
title: Our first team post
body: Hi! This is an area for us to collaborate as a team.
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/team-discussion'
examples:
default:
$ref: '#/components/examples/team-discussion'
x-github:
triggersNotification: true
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: discussions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}:
get:
summary: GitHub Get Discussion
description: >-
Get a specific discussion on a team's page.
**Note:** You can also specify a team by `org_id` and `team_id` using
the route `GET
/organizations/{org_id}/team/{team_id}/discussions/{discussion_number}`.
OAuth app tokens and personal access tokens (classic) need the
`read:discussion` scope to use this endpoint.
tags:
- Discussions
- Get
operationId: getDiscussion
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/teams/discussions#get-a-discussion
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
- $ref: '#/components/parameters/discussion-number'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/team-discussion'
examples:
default:
$ref: '#/components/examples/team-discussion'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: discussions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update Discussion
description: >-
Edits the title and body text of a discussion post. Only the parameters
you provide are updated.
**Note:** You can also specify a team by `org_id` and `team_id` using
the route `PATCH
/organizations/{org_id}/team/{team_id}/discussions/{discussion_number}`.
OAuth app tokens and personal access tokens (classic) need the
`write:discussion` scope to use this endpoint.
tags:
- Discussions
- Update
operationId: updateDiscussion
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/teams/discussions#update-a-discussion
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
- $ref: '#/components/parameters/discussion-number'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: The discussion post's title.
body:
type: string
description: The discussion post's body text.
examples:
default:
value:
title: Welcome to our first team post
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/team-discussion'
examples:
default:
$ref: '#/components/examples/team-discussion-2'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: discussions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete Discussion
description: >-
Delete a discussion from a team's page.
**Note:** You can also specify a team by `org_id` and `team_id` using
the route `DELETE
/organizations/{org_id}/team/{team_id}/discussions/{discussion_number}`.
OAuth app tokens and personal access tokens (classic) need the
`write:discussion` scope to use this endpoint.
tags:
- Delete
- Discussions
operationId: deleteDiscussion
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/teams/discussions#delete-a-discussion
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/team-slug'
- $ref: '#/components/parameters/discussion-number'
responses:
'204':
description: Response
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: teams
subcategory: discussions
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/teams/{team_slug}/discussions/{discussion_number}/comments:
get:
summary: GitHub List Discussion Comments
description: >-
List all comments on a team discussion.
**Note:** You can also specify a team by `org_id` and `team_id` using
the route `GET
/organizations/{org_id}/team/{team_id}/discussions/{discussion_number}/comments`.
OAuth app tokens and personal access tokens (classic) need the
`read:discussion` scope to use this endpoint.
tags:
- Comments
- Discussions
- Lists
operationId: listDiscussionComments
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/ent
# --- truncated at 32 KB (287 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-teams-openapi.yml