GitHub v3 REST API

Add or update team membership for a user If the user is already a member of the team's organization, this endpoint will add the user to the team. To add a membership between an organization member and a team, the authenticated user must be an organization owner or a team maintainer. If the user is unaffiliated with the team's organization, this endpoint will send an invitation to the user via email. This newly-created membership will be in the "pending" state until the user accepts the invitation, at which point the membership will transition to the "active" state and the user will be added as a member of the team. To add a membership between an unaffiliated user and a team, the authenticated user must be an organization owner. If the user is already a member of the team, this endpoint will update the role of the team member's role. To update the membership of a team member, the authenticated user must be an organization owner or a team maintainer.

Add or update team project permissions Adds an organization project to a team. To add a project to a team or update the team's permission on a project, the authenticated user must have `admin` permissions for the project. The project and team must be part of the same organization.

Add or update team repository permissions 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 verbs](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#http-verbs)."

Check team permissions for a project Checks whether a team has `read`, `write`, or `admin` permissions for an organization project. If you pass the `hellcat-preview` media type, the response will include projects inherited from a parent team.

Check team permissions for a repository **Note**: If you pass the `hellcat-preview` media type, repositories inherited through a parent team will be checked. You can also get information about the specified repository, including what permissions the team grants on it, by passing the following custom [media type](https://docs.github.com/[email protected]/rest/overview/media-types/) via the `Accept` header:

Create a team 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://help.github.com/en/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://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/about-teams)".

Create a discussion Creates a new discussion post on a team's page. OAuth access tokens require the `write:discussion` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). This endpoint triggers [notifications](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/about-notifications). Creating content too quickly using this endpoint may result in secondary rate limiting. See "[Secondary rate limits](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#secondary-rate-limits)" for details.

Create a discussion comment Creates a new comment on a team discussion. OAuth access tokens require the `write:discussion` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). This endpoint triggers [notifications](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/about-notifications). Creating content too quickly using this endpoint may result in secondary rate limiting. See "[Secondary rate limits](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#secondary-rate-limits)" for details.

Delete a team To delete a team, the authenticated user must be an organization owner or team maintainer. If you are an organization owner and you pass the `hellcat-preview` media type, deleting a parent team will delete all of its child teams as well.

Delete a discussion from a team's page. OAuth access tokens require the `write:discussion` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Delete a discussion comment Deletes a comment on a team discussion. OAuth access tokens require the `write:discussion` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Get a team

Get a team by name Gets a team using the team's `slug`. GitHub Enterprise Server generates the `slug` from the 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}`.

Get a discussion Get a specific discussion on a team's page. OAuth access tokens require the `read:discussion` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Get a discussion comment Get a specific comment on a team discussion. OAuth access tokens require the `read:discussion` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Get team member (Legacy) The "Get team member" endpoint (described below) is deprecated. We recommend using the [Get team membership for a user](https://docs.github.com/[email protected]/rest/reference/teams#get-team-membership-for-a-user) endpoint instead. It allows you to get both active and pending memberships. To list members in a team, the team must be visible to the authenticated user.

Get team membership for a user If you pass the `hellcat-preview` media type, team members will include the members of child teams. To get a user's membership with a team, the team must be visible to the authenticated user. **Note:** The response contains the `state` of the membership and the member's `role`. The `role` for organization owners is set to `maintainer`. For more information about `maintainer` roles, see [Create a team](https://docs.github.com/[email protected]/rest/reference/teams#create-a-team).

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

List child teams You must use the `hellcat-preview` media type to use this endpoint.

List discussion comments List all comments on a team discussion. OAuth access tokens require the `read:discussion` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

List discussions List all discussions on a team's page. OAuth access tokens require the `read:discussion` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

List teams for the authenticated user List all of the teams across all of the organizations to which the authenticated user belongs. This method requires `user`, `repo`, or `read:org` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/) when authenticating via [OAuth](https://docs.github.com/[email protected]/apps/building-oauth-apps/).

List team members If you pass the `hellcat-preview` media type, team members will include the members of child teams. To list members in a team, the team must be visible to the authenticated user.

List team projects Lists the organization projects for a team. If you are an [authenticated](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#authentication) site administrator for your Enterprise instance, you will be able to list all projects for the team. If you pass the `hellcat-preview` media type, the response will include projects inherited from a parent team.

List team repositories **Note**: If you pass the `hellcat-preview` media type, the response will include any repositories inherited through a parent team. If you are an [authenticated](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#authentication) site administrator for your Enterprise instance, you will be able to list all repositories for the team.

Remove team member (Legacy) The "Remove team member" endpoint (described below) is deprecated. We recommend using the [Remove team membership for a user](https://docs.github.com/[email protected]/rest/reference/teams#remove-team-membership-for-a-user) endpoint instead. It allows you to remove both active and pending memberships. Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see [GitHub's products](https://help.github.com/github/getting-started-with-github/githubs-products) in the GitHub Help documentation. To remove a team member, the authenticated user must have 'admin' permissions to the team or be an owner of the org that the team is associated with. Removing a team member does not delete the user, it just removes them from the team. **Note:** When you have team synchronization set up for a team with your organization's identity provider (IdP), you will see an error if you attempt to use the API for making changes to the team's membership. If you have access to manage group membership in your IdP, you can manage GitHub Enterprise Server team membership through your identity provider, which automatically adds and removes team members in an organization. For more information, see "[Synchronizing teams between your identity provider and GitHub Enterprise Server](https://help.github.com/articles/synchronizing-teams-between-your-identity-provider-and-github/)."

Remove team membership for a user 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.

Remove a project from a team Removes an organization project from a team. An organization owner or a team maintainer can remove any project from the team. To remove a project from a team as an organization member, the authenticated user must have `read` access to both the team and project, or `admin` access to the team or project. **Note:** This endpoint removes the project from the team, but does not delete it.

Remove a repository from a team 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.

Update a team To edit a team, the authenticated user must either be an organization owner or a team maintainer. **Note:** With nested teams, the `privacy` for parent teams cannot be `secret`.

Update a discussion Edits the title and body text of a discussion post. Only the parameters you provide are updated. OAuth access tokens require the `write:discussion` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Update a discussion comment Edits the body text of a discussion comment. OAuth access tokens require the `write:discussion` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Add an email address for the authenticated user This endpoint is accessible with the `user` scope.

Check if a user follows another user

Check if a person is followed by the authenticated user

Create a GPG key for the authenticated user Adds a GPG key to the authenticated user's GitHub account. Requires that you are authenticated via Basic Auth, or OAuth with at least `write:gpg_key` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Create a public SSH key for the authenticated user Adds a public SSH key to the authenticated user's GitHub account. Requires that you are authenticated via Basic Auth, or OAuth with at least `write:public_key` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Delete an email address for the authenticated user This endpoint is accessible with the `user` scope.

Delete a GPG key for the authenticated user Removes a GPG key from the authenticated user's GitHub account. Requires that you are authenticated via Basic Auth or via OAuth with at least `admin:gpg_key` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Delete a public SSH key for the authenticated user Removes a public SSH key from the authenticated user's GitHub account. Requires that you are authenticated via Basic Auth or via OAuth with at least `admin:public_key` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Follow a user Note that you'll need to set `Content-Length` to zero when calling out to this endpoint. For more information, see "[HTTP verbs](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#http-verbs)." Following a user requires the user to be logged in and authenticated with basic auth or OAuth with the `user:follow` scope.

Get the authenticated user If the authenticated user is authenticated through basic authentication or OAuth with the `user` scope, then the response lists public and private profile information. If the authenticated user is authenticated through OAuth without the `user` scope, then the response lists only public profile information.

Get a user Provides publicly available information about someone with a GitHub account. GitHub Apps with the `Plan` user permission can use this endpoint to retrieve information about a user's GitHub Enterprise Server plan. The GitHub App must be authenticated as a user. See "[Identifying and authorizing users for GitHub Apps](https://docs.github.com/[email protected]/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/)" for details about authentication. For an example response, see 'Response with GitHub Enterprise Server plan information' below" The `email` key in the following response is the publicly visible email address from your GitHub Enterprise Server [profile page](https://github.com/settings/profile). When setting up your profile, you can select a primary email address to be “public” which provides an email entry for this endpoint. If you do not set a public email address for `email`, then it will have a value of `null`. You only see publicly visible email addresses when authenticated with GitHub Enterprise Server. For more information, see [Authentication](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#authentication). The Emails API enables you to list all of your email addresses, and toggle a primary email to be visible publicly. For more information, see "[Emails API](https://docs.github.com/[email protected]/rest/reference/users#emails)".

Get contextual information for a user Provides hovercard information when authenticated through basic auth or OAuth with the `repo` scope. You can find out more about someone in relation to their pull requests, issues, repositories, and organizations. The `subject_type` and `subject_id` parameters provide context for the person's hovercard, which returns more information than without the parameters. For example, if you wanted to find out more about `octocat` who owns the `Spoon-Knife` repository via cURL, it would look like this: ```shell curl -u username:token https://api.github.com/users/octocat/hovercard?subject_type=repository&subject_id=1300192 ```

Get a GPG key for the authenticated user View extended details for a single GPG key. Requires that you are authenticated via Basic Auth or via OAuth with at least `read:gpg_key` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

Get a public SSH key for the authenticated user View extended details for a single public SSH key. Requires that you are authenticated via Basic Auth or via OAuth with at least `read:public_key` [scope](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).

List users Lists all users, in the order that they signed up on GitHub Enterprise Server. This list includes personal user accounts and organization accounts. Note: Pagination is powered exclusively by the `since` parameter. Use the [Link header](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#link-header) to get the URL for the next page of users.

List email addresses for the authenticated user Lists all of your email addresses, and specifies which one is visible to the public. This endpoint is accessible with the `user:email` scope.

List the people the authenticated user follows Lists the people who the authenticated user follows.

List followers of the authenticated user Lists the people following the authenticated user.