Org Teams API

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 “user” scope.

List teams

GET /orgs/:org/teams

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "url": "https://api.github.com/teams/1",
    "name": "Owners",
    "id": 1
  }
]

Get team

GET /teams/:id

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "url": "https://api.github.com/teams/1",
  "name": "Owners",
  "id": 1,
  "permission": "admin",
  "members_count": 3,
  "repos_count": 10
}

Create team

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

POST /orgs/:org/teams

Input

name
Required string
repo_names
Optional array of strings
permission
Optional string

pull - team members can pull, but not push to or administer these repositories. Default

push - team members can pull and push, but not administer these repositories.

admin - team members can pull, push and administer these repositories.

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

Response

Status: 201 Created
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "url": "https://api.github.com/teams/1",
  "name": "Owners",
  "id": 1,
  "permission": "admin",
  "members_count": 3,
  "repos_count": 10
}

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

Input

name
Required string
permission
Optional string 
{
  "name": "new team name",
  "permission": "push"
}

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "url": "https://api.github.com/teams/1",
  "name": "Owners",
  "id": 1,
  "permission": "admin",
  "members_count": 3,
  "repos_count": 10
}

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
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.github.com/users/octocat"
  }
]

Get team member

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/:user

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

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 org that the team is associated with.

PUT /teams/:id/members/:user

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": "Validation Failed",
  "errors": [
    {
      "code": "org",
      "field": "user",
      "resource": "TeamMember"
    }
  ]
}

Remove team member

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 remove them from the team.

DELETE /teams/:id/members/:user

Response

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

List team repos

GET /teams/:id/repos

Response

Status: 200 OK
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": "somehexcode",
      "url": "https://api.github.com/users/octocat"
    },
    "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": 9,
    "forks_count": 9,
    "watchers": 80,
    "watchers_count": 80,
    "size": 108,
    "master_branch": "master",
    "open_issues": 0,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z"
  }
]

Get team repo

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

Response if repo is managed by this team

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

Response if repo is not managed by this team

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

Add team repo

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

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

Response

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

If you attempt to add a repo 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 repo

In order to remove a repo from a team, the authenticated user must be an owner of the org that the team is associated with. NOTE: This does not delete the repo, 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