Teams

List teams
Get team
Create team
Edit team
Delete team
List team members
Get team member
Add team member
Remove team member
Get team membership
Add team membership
Remove team membership
List team repos
Check if a team manages a repository
Add team repository
Remove team repository
List user teams

All actions against teams require at a minimum an authenticated user who is a member of the Owners team in the :org being managed. Additionally, OAuth users require the “read:org” scope.

List teams

GET /orgs/:org/teams

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

[
  {
    "id": 1,
    "url": "https://api.github.com/teams/1",
    "name": "Justice League",
    "slug": "justice-league",
    "description": "A great team.",
    "permission": "admin",
    "members_url": "https://api.github.com/teams/1/members{/member}",
    "repositories_url": "https://api.github.com/teams/1/repos"
  }
]

Get team

GET /teams/:id

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "id": 1,
  "url": "https://api.github.com/teams/1",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "permission": "admin",
  "members_url": "https://api.github.com/teams/1/members{/member}",
  "repositories_url": "https://api.github.com/teams/1/repos",
  "members_count": 3,
  "repos_count": 10,
  "organization": {
    "login": "github",
    "id": 1,
    "url": "https://api.github.com/orgs/github",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  }
}

Create team

In order to create a team, the authenticated user must be an owner of :org.

POST /orgs/:org/teams

Parameters

Name	Type	Description
`name`	`string`	Required. The name of the team.
`description`	`string`	The description of the team.
`repo_names`	`array` of `strings`	The repositories to add the team to.
`permission`	`string`	The permission to grant the team. Can be one of: * `pull` - team members can pull, but not push to or administer these repositories. * `push` - team members can pull and push, but not administer these repositories. * `admin` - team members can pull, push and administer these repositories. Default: `pull`

Example

{
  "name": "new team",
  "description": "team description",
  "permission": "push",
  "repo_names": [
    "github/dotfiles"
  ]
}

Response

Status: 201 Created
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "id": 1,
  "url": "https://api.github.com/teams/1",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "permission": "admin",
  "members_url": "https://api.github.com/teams/1/members{/member}",
  "repositories_url": "https://api.github.com/teams/1/repos",
  "members_count": 3,
  "repos_count": 10,
  "organization": {
    "login": "github",
    "id": 1,
    "url": "https://api.github.com/orgs/github",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  }
}

Edit team

In order to edit a team, the authenticated user must be an owner of the org that the team is associated with.

PATCH /teams/:id

Parameters

Name	Type	Description
`name`	`string`	Required. The name of the team.
`description`	`string`	The description of the team.
`permission`	`string`	The permission to grant the team. Can be one of: * `pull` - team members can pull, but not push to or administer these repositories. * `push` - team members can pull and push, but not administer these repositories. * `admin` - team members can pull, push and administer these repositories. Default: `pull`

Example

{
  "name": "new team description",
  "permission": "push"
}

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "id": 1,
  "url": "https://api.github.com/teams/1",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "permission": "admin",
  "members_url": "https://api.github.com/teams/1/members{/member}",
  "repositories_url": "https://api.github.com/teams/1/repos",
  "members_count": 3,
  "repos_count": 10,
  "organization": {
    "login": "github",
    "id": 1,
    "url": "https://api.github.com/orgs/github",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  }
}

Delete team

In order to delete a team, the authenticated user must be an owner of the org that the team is associated with.

DELETE /teams/:id

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

List team members

In order to list members in a team, the authenticated user must be a member of the team.

GET /teams/:id/members

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

[
  {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
]

Get team member

Deprecation notice

The "Get team member" API (described below) is deprecated and is scheduled for removal in the next major version of the API. We recommend using the Get team membership API instead. It allows you to get both active and pending memberships.

In order to get if a user is a member of a team, the authenticated user must be a member of the team.

GET /teams/:id/members/:username

Response if user is a member

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Response if user is not a member

Status: 404 Not Found
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Add team member

Deprecation notice

The "Add team member" API (described below) is deprecated and is scheduled for removal in the next major version of the API. We recommend using the Add team membership API instead. It allows you to invite new organization members to your teams.

In order to add a user to 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, and the user being added must already be a member of at least one other team on the same organization.

PUT /teams/:id/members/:username

Note that you’ll need to set Content-Length to zero when calling out to this endpoint. For more information, see “HTTP verbs.”

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

If you attempt to add an organization to a team, you will get this:

Status: 422 Unprocessable Entity
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "message": "Cannot add an organization as a member.",
  "errors": [
    {
      "code": "org",
      "field": "user",
      "resource": "TeamMember"
    }
  ]
}

If you attempt to add a user to a team and that user is not a member of at least one other team on the same organization, you will get this:

Status: 422 Unprocessable Entity
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "message": "User isn't a member of this organization. Please invite them first.",
  "errors": [
    {
      "code": "unaffiliated",
      "field": "user",
      "resource": "TeamMember"
    }
  ]
}

Remove team member

Deprecation notice

The "Remove team member" API (described below) is deprecated and is scheduled for removal in the next major version of the API. We recommend using the Remove team membership API instead. It allows you to remove both active and pending memberships.

In order to remove a user from a team, the authenticated user must have ‘admin’ permissions to the team or be an owner of the org that the team is associated with. NOTE: This does not delete the user, it just removes them from the team.

DELETE /teams/:id/members/:username

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Get team membership

In order to get a user’s membership with a team, the authenticated user must be a member of the team or an owner of the team’s organization.

GET /teams/:id/memberships/:username

Response if user has an active membership with team

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "url": "https://api.github.com/teams/1/memberships/octocat",
  "state": "active"
}

Response if user has a pending membership with team

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "url": "https://api.github.com/teams/1/memberships/octocat",
  "state": "pending"
}

Response if user has no membership with team

Status: 404 Not Found
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Add team membership

In order to add 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.

If the user is already a part of the team’s organization (meaning they’re on at least one other team in the organization), this endpoint will add the user to the team.

If the user is completely unaffiliated with the team’s organization (meaning they’re on none of the organization’s teams), 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.

PUT /teams/:id/memberships/:username

Response if user’s membership with team is now active

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "url": "https://api.github.com/teams/1/memberships/octocat",
  "state": "active"
}

Response if user’s membership with team is now pending

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "url": "https://api.github.com/teams/1/memberships/octocat",
  "state": "pending"
}

If you attempt to add an organization to a team, you will get this:

Status: 422 Unprocessable Entity
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "message": "Cannot add an organization as a member.",
  "errors": [
    {
      "code": "org",
      "field": "user",
      "resource": "TeamMember"
    }
  ]
}

Remove team membership

In order 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. NOTE: This does not delete the user, it just removes their membership from the team.

DELETE /teams/:id/memberships/:username

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

List team repos

GET /teams/:id/repos

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

[
  {
    "id": 1296269,
    "owner": {
      "login": "octocat",
      "id": 1,
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "description": "This your first repo!",
    "private": false,
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "html_url": "https://github.com/octocat/Hello-World",
    "clone_url": "https://github.com/octocat/Hello-World.git",
    "git_url": "git://github.com/octocat/Hello-World.git",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "svn_url": "https://svn.github.com/octocat/Hello-World",
    "mirror_url": "git://git.example.com/octocat/Hello-World",
    "homepage": "https://github.com",
    "language": null,
    "forks_count": 9,
    "stargazers_count": 80,
    "watchers_count": 80,
    "size": 108,
    "default_branch": "master",
    "open_issues_count": 0,
    "has_issues": true,
    "has_wiki": true,
    "has_pages": false,
    "has_downloads": true,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    }
  }
]

Check if a team manages a repository

GET /teams/:id/repos/:owner/:repo

Response if repository is managed by this team

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Response if repository is not managed by this team

Status: 404 Not Found
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Add team repository

In order to add a repository to a team, the authenticated user must be an owner of the org that the team is associated with. Also, the repository must be owned by the organization, or a direct fork of a repository owned by the organization.

PUT /teams/:id/repos/:org/:repo

Note that you’ll need to set Content-Length to zero when calling out to this endpoint. For more information, see “HTTP verbs.”

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

If you attempt to add a repository to a team that is not owned by the organization, you get:

Status: 422 Unprocessable Entity
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "message": "Validation Failed",
  "errors": [
    {
      "code": "not_owned",
      "field": "repository",
      "resource": "TeamMember"
    }
  ]
}

Remove team repository

In order to remove a repository from a team, the authenticated user must be an owner of the org that the team is associated with. Also, since the Owners team always has access to all repositories in the organization, repositories cannot be removed from the Owners team. NOTE: This does not delete the repository, it just removes it from the team.

DELETE /teams/:id/repos/:owner/:repo

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

List user teams

List all of the teams across all of the organizations to which the authenticated user belongs. This method requires user or repo scope when authenticating via OAuth.

GET /user/teams

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

[
  {
    "id": 1,
    "url": "https://api.github.com/teams/1",
    "name": "Justice League",
    "slug": "justice-league",
    "description": "A great team.",
    "permission": "admin",
    "members_url": "https://api.github.com/teams/1/members{/member}",
    "repositories_url": "https://api.github.com/teams/1/repos",
    "members_count": 3,
    "repos_count": 10,
    "organization": {
      "login": "github",
      "id": 1,
      "url": "https://api.github.com/orgs/github",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    }
  }
]