Teams API Reference

List teams

GET /orgs/{org}/teams

Lists all teams in an organization that are visible to the authenticated user.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
`team_type`	query	no	Filter team results by their type. For more information, see "What kind of team should I use?"

Responses

Status	Description	Has JSON body
200	Response	yes
403	Forbidden	yes

Create a team

POST /orgs/{org}/teams

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."

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.

Responses

Status	Description	Has JSON body
201	Response	yes
422	Validation failed, or the endpoint has been spammed.	yes
403	Forbidden	yes

Get a team by name

GET /orgs/{org}/teams/{team_slug}

Gets a team using the team's slug. To create the slug, GitHub 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.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes

Update a team

PATCH /orgs/{org}/teams/{team_slug}

To edit a team, the authenticated user must either be an organization owner or a team maintainer.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.

Responses

Status	Description	Has JSON body
200	Response when the updated information already exists	yes
201	Response	yes
404	Resource not found	yes
422	Validation failed, or the endpoint has been spammed.	yes
403	Forbidden	yes

Delete a team

DELETE /orgs/{org}/teams/{team_slug}

To delete a team, the authenticated user must be an organization owner or team maintainer.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.

Responses

Status	Description	Has JSON body
204	Response	no
422	Unprocessable entity if you attempt to modify an enterprise team at the organization level.	no

List pending team invitations

GET /orgs/{org}/teams/{team_slug}/invitations

The return hash contains a role field which refers to the Organization Invitation role and will be one of the following values: direct_member, admin, billing_manager, hiring_manager, or reinstate. If the invitee is not a GitHub member, the login field in the return hash will be null.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
422	Unprocessable entity if you attempt to modify an enterprise team at the organization level.	no

List team members

GET /orgs/{org}/teams/{team_slug}/members

Team members will include the members of child teams.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.
`role`	query	no	Filters members returned by their role in the team.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes

Get team membership for a user

GET /orgs/{org}/teams/{team_slug}/memberships/{username}

Team members will include the members of child teams.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
200	Response	yes
404	if user has no team membership	no

Add or update team membership for a user

PUT /orgs/{org}/teams/{team_slug}/memberships/{username}

Adds an organization member to a team. An authenticated organization owner or team maintainer can add organization members to a team.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
200	Response	yes
403	Forbidden if team synchronization is set up	no
422	Unprocessable Entity if you attempt to add an organization to a team	no

Remove team membership for a user

DELETE /orgs/{org}/teams/{team_slug}/memberships/{username}

To remove a membership between a user and a team, the authenticated user must have 'admin' permissions to the team or be an owner of the organization that the team is associated with. Removing team membership does not delete the user, it just removes their membership from the team.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	Response	no
403	Forbidden if team synchronization is set up	no

List team repositories

GET /orgs/{org}/teams/{team_slug}/repos

Lists a team's repositories visible to the authenticated user.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes

Check team permissions for a repository

GET /orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}

Checks whether a team has admin, push, maintain, triage, or pull permission for a repository. Repositories inherited through a parent team will also be checked.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.

Responses

Status	Description	Has JSON body
200	Alternative response with repository permissions	yes
204	Response if team has permission for the repository. This is the response when the repository media type hasn't been provded in the Accept header.	no
404	Not Found if team does not have permission for the repository	no

Add or update team repository permissions

PUT /orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}

To add a repository to a team or update the team's permission on a repository, the authenticated user must have admin access to the repository, and must be able to see the team. The repository must be owned by the organization, or a direct fork of a repository owned by the organization. You will get a 422 Unprocessable Entity status if you attempt to add a repository to a team that is not owned by the organization. Note that, if you choose not to pass any parameters, you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP method."

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.

Responses

Status	Description	Has JSON body
204	Response	no

Remove a repository from a team

DELETE /orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}

If the authenticated user is an organization owner or a team maintainer, they can remove any repositories from the team. To remove a repository from a team as an organization member, the authenticated user must have admin access to the repository and must be able to see the team. This does not delete the repository, it just removes it from the team.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.

Responses

Status	Description	Has JSON body
204	Response	no

List child teams

GET /orgs/{org}/teams/{team_slug}/teams

Lists the child teams of the team specified by {team_slug}.

Parameters

Name	In	Required	Description
`org`	path	yes	The organization name. The name is not case sensitive.
`team_slug`	path	yes	The slug of the team name.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	if child teams exist	yes

Get a team (Legacy)

GET /teams/{team_id}

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes

Update a team (Legacy)

PATCH /teams/{team_id}

To edit a team, the authenticated user must either be an organization owner or a team maintainer.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.

Responses

Status	Description	Has JSON body
200	Response when the updated information already exists	yes
201	Response	yes
404	Resource not found	yes
422	Validation failed, or the endpoint has been spammed.	yes
403	Forbidden	yes

Delete a team (Legacy)

DELETE /teams/{team_id}

To delete a team, the authenticated user must be an organization owner or team maintainer.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.

Responses

Status	Description	Has JSON body
204	Response	no
404	Resource not found	yes
422	Validation failed, or the endpoint has been spammed.	yes

List pending team invitations (Legacy)

GET /teams/{team_id}/invitations

The return hash contains a role field which refers to the Organization Invitation role and will be one of the following values: direct_member, admin, billing_manager, hiring_manager, or reinstate. If the invitee is not a GitHub member, the login field in the return hash will be null.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes

List team members (Legacy)

GET /teams/{team_id}/members

Team members will include the members of child teams.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`role`	query	no	Filters members returned by their role in the team.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes

Get team member (Legacy)

GET /teams/{team_id}/members/{username}

The "Get team member" endpoint (described below) is closing down.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	if user is a member	no
404	if user is not a member	no

Add team member (Legacy)

PUT /teams/{team_id}/members/{username}

The "Add team member" endpoint (described below) is closing down.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	Response	no
404	Not Found if team synchronization is set up	no
422	Unprocessable Entity if you attempt to add an organization to a team or you attempt to add a user to a team when they are not a member of at least one other team in the same organization	no
403	Forbidden	yes

Remove team member (Legacy)

DELETE /teams/{team_id}/members/{username}

The "Remove team member" endpoint (described below) is closing down.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	Response	no
404	Not Found if team synchronization is setup	no

Get team membership for a user (Legacy)

GET /teams/{team_id}/memberships/{username}

Team members will include the members of child teams.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes

Add or update team membership for a user (Legacy)

PUT /teams/{team_id}/memberships/{username}

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
200	Response	yes
403	Forbidden if team synchronization is set up	no
422	Unprocessable Entity if you attempt to add an organization to a team	no
404	Resource not found	yes

Remove team membership for a user (Legacy)

DELETE /teams/{team_id}/memberships/{username}

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`username`	path	yes	The handle for the GitHub user account.

Responses

Status	Description	Has JSON body
204	Response	no
403	if team synchronization is set up	no

List team repositories (Legacy)

GET /teams/{team_id}/repos

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
404	Resource not found	yes

Check team permissions for a repository (Legacy)

GET /teams/{team_id}/repos/{owner}/{repo}

You can also get information about the specified repository, including what permissions the team grants on it, by passing the following custom media type via the Accept header:

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.

Responses

Status	Description	Has JSON body
200	Alternative response with extra repository information	yes
204	Response if repository is managed by this team	no
404	Not Found if repository is not managed by this team	no

Add or update team repository permissions (Legacy)

PUT /teams/{team_id}/repos/{owner}/{repo}

To add a repository to a team or update the team's permission on a repository, the authenticated user must have admin access to the repository, and must be able to see the team. The repository must be owned by the organization, or a direct fork of a repository owned by the organization. You will get a 422 Unprocessable Entity status if you attempt to add a repository to a team that is not owned by the organization.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.

Responses

Status	Description	Has JSON body
204	Response	no
403	Forbidden	yes
422	Validation failed, or the endpoint has been spammed.	yes

Remove a repository from a team (Legacy)

DELETE /teams/{team_id}/repos/{owner}/{repo}

If the authenticated user is an organization owner or a team maintainer, they can remove any repositories from the team. To remove a repository from a team as an organization member, the authenticated user must have admin access to the repository and must be able to see the team. NOTE: This does not delete the repository, it just removes it from the team.

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`owner`	path	yes	The account owner of the repository. The name is not case sensitive.
`repo`	path	yes	The name of the repository without the `.git` extension. The name is not case sensitive.

Responses

Status	Description	Has JSON body
204	Response	no

List child teams (Legacy)

GET /teams/{team_id}/teams

Parameters

Name	In	Required	Description
`team_id`	path	yes	The unique identifier of the team.
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	if child teams exist	yes
404	Resource not found	yes
403	Forbidden	yes
422	Validation failed, or the endpoint has been spammed.	yes

List teams for the authenticated user

GET /user/teams

List all of the teams across all of the organizations to which the authenticated

Parameters

Name	In	Required	Description
`per_page`	query	no	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
`page`	query	no	The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Responses

Status	Description	Has JSON body
200	Response	yes
304	Not modified	no
404	Resource not found	yes
403	Forbidden	yes