Explore by product

REST API
English

This version of GitHub Enterprise was discontinued on 2020-11-12. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Article version: Enterprise Server 2.19
Free, Pro, and Team Enterprise Server 2.22 Enterprise Server 2.21 Enterprise Server 2.20 Enterprise Server 2.19 GitHub AE
Article version: Enterprise Server 2.19
Free, Pro, and Team Enterprise Server 2.22 Enterprise Server 2.21 Enterprise Server 2.20 Enterprise Server 2.19 GitHub AE

Teams

In this article

This API is only available to authenticated members of the team's organization. OAuth access tokens require the read:org scope. GitHub generates the team's slug from the team name.

List teams

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

get /orgs/{org}/teams

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/teams
JavaScript (@octokit/core.js) 
await octokit.request('GET /orgs/{org}/teams', {
  org: 'org'
})

Default response

Status: 200 OK
[
  {
    "id": 1,
    "node_id": "MDQ6VGVhbTE=",
    "url": "https://api.github.com/teams/1",
    "html_url": "https://api.github.com/teams/justice-league",
    "name": "Justice League",
    "slug": "justice-league",
    "description": "A great team.",
    "privacy": "closed",
    "permission": "admin",
    "members_url": "https://api.github.com/teams/1/members{/member}",
    "repositories_url": "https://api.github.com/teams/1/repos",
    "parent": null
  }
]

Forbidden

Status: 403 Forbidden

Notes

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

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

post /orgs/{org}/teams

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
name string body

Required. The name of the team.
description string body

The description of the team.
maintainers array of strings body

List GitHub IDs for organization members who will become team maintainers.
repo_names array of strings body

The full name (e.g., "organization-name/repository-name") of repositories to add the team to.
privacy string body

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
permission string body

Deprecated. The permission that new repositories will be added to the team with when none is specified. Can be one of:
* pull - team members can pull, but not push to or administer newly-added repositories.
* push - team members can pull and push, but not administer newly-added repositories.
* admin - team members can pull, push and administer newly-added repositories.

Default: pull
parent_team_id integer body

The ID of a team to set as the parent team.

Code samples

Shell 
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/teams \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js) 
await octokit.request('POST /orgs/{org}/teams', {
  org: 'org',
  name: 'name'
})

Default response

Status: 201 Created
{
  "id": 1,
  "node_id": "MDQ6VGVhbTE=",
  "url": "https://api.github.com/teams/1",
  "html_url": "https://api.github.com/teams/justice-league",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "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,
  "created_at": "2017-07-14T16:53:42Z",
  "updated_at": "2017-08-17T12:37:15Z",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization",
    "name": "github",
    "company": "GitHub",
    "blog": "https://github.com/blog",
    "location": "San Francisco",
    "email": "octocat@github.com",
    "has_organization_projects": true,
    "has_repository_projects": true,
    "public_repos": 2,
    "public_gists": 1,
    "followers": 20,
    "following": 0,
    "html_url": "https://github.com/octocat",
    "created_at": "2008-01-14T04:33:35Z",
    "updated_at": "2017-08-17T12:37:15Z",
    "type": "Organization"
  },
  "ldap_dn": "uid=asdf,ou=users,dc=github,dc=com"
}

Forbidden

Status: 403 Forbidden

Validation failed

Status: 422 Unprocessable Entity

Notes

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 /orgs/{org}/teams/{team_slug}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
team_slug string path

team_slug parameter

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/teams/TEAM_SLUG
JavaScript (@octokit/core.js) 
await octokit.request('GET /orgs/{org}/teams/{team_slug}', {
  org: 'org',
  team_slug: 'team_slug'
})

Default response

Status: 200 OK
{
  "id": 1,
  "node_id": "MDQ6VGVhbTE=",
  "url": "https://api.github.com/teams/1",
  "html_url": "https://api.github.com/teams/justice-league",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "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,
  "created_at": "2017-07-14T16:53:42Z",
  "updated_at": "2017-08-17T12:37:15Z",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization",
    "name": "github",
    "company": "GitHub",
    "blog": "https://github.com/blog",
    "location": "San Francisco",
    "email": "octocat@github.com",
    "has_organization_projects": true,
    "has_repository_projects": true,
    "public_repos": 2,
    "public_gists": 1,
    "followers": 20,
    "following": 0,
    "html_url": "https://github.com/octocat",
    "created_at": "2008-01-14T04:33:35Z",
    "updated_at": "2017-08-17T12:37:15Z",
    "type": "Organization"
  },
  "ldap_dn": "uid=asdf,ou=users,dc=github,dc=com"
}

Resource not found

Status: 404 Not Found

Notes

get /teams/{team_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

team_id integer path

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/teams/42
JavaScript (@octokit/core.js) 
await octokit.request('GET /teams/{team_id}', {
  team_id: 42
})

Default response

Status: 200 OK
{
  "id": 1,
  "node_id": "MDQ6VGVhbTE=",
  "url": "https://api.github.com/teams/1",
  "html_url": "https://api.github.com/teams/justice-league",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "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,
  "created_at": "2017-07-14T16:53:42Z",
  "updated_at": "2017-08-17T12:37:15Z",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization",
    "name": "github",
    "company": "GitHub",
    "blog": "https://github.com/blog",
    "location": "San Francisco",
    "email": "octocat@github.com",
    "has_organization_projects": true,
    "has_repository_projects": true,
    "public_repos": 2,
    "public_gists": 1,
    "followers": 20,
    "following": 0,
    "html_url": "https://github.com/octocat",
    "created_at": "2008-01-14T04:33:35Z",
    "updated_at": "2017-08-17T12:37:15Z",
    "type": "Organization"
  },
  "ldap_dn": "uid=asdf,ou=users,dc=github,dc=com"
}

Notes

Preview notice

The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.hellcat-preview+json

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.

patch /teams/{team_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

team_id integer path
name string body

Required. The name of the team.
description string body

The description of the team.
privacy string body

The level of privacy this team should have. Editing teams without specifying this parameter leaves privacy intact. 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.
permission string body

Deprecated. The permission that new repositories will be added to the team with when none is specified. Can be one of:
* pull - team members can pull, but not push to or administer newly-added repositories.
* push - team members can pull and push, but not administer newly-added repositories.
* admin - team members can pull, push and administer newly-added repositories.

Default: pull
parent_team_id integer body

The ID of a team to set as the parent team. Note: You must pass the hellcat-preview media type to use this parameter.

Code samples

Shell 
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/teams/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js) 
await octokit.request('PATCH /teams/{team_id}', {
  team_id: 42,
  name: 'name'
})

Default response

Status: 201 Created
{
  "id": 1,
  "node_id": "MDQ6VGVhbTE=",
  "url": "https://api.github.com/teams/1",
  "html_url": "https://api.github.com/teams/justice-league",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "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,
  "created_at": "2017-07-14T16:53:42Z",
  "updated_at": "2017-08-17T12:37:15Z",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization",
    "name": "github",
    "company": "GitHub",
    "blog": "https://github.com/blog",
    "location": "San Francisco",
    "email": "octocat@github.com",
    "has_organization_projects": true,
    "has_repository_projects": true,
    "public_repos": 2,
    "public_gists": 1,
    "followers": 20,
    "following": 0,
    "html_url": "https://github.com/octocat",
    "created_at": "2008-01-14T04:33:35Z",
    "updated_at": "2017-08-17T12:37:15Z",
    "type": "Organization"
  },
  "ldap_dn": "uid=asdf,ou=users,dc=github,dc=com"
}

Notes

Preview notice

The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.hellcat-preview+json

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 /teams/{team_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

team_id integer path

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/teams/42
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /teams/{team_id}', {
  team_id: 42
})

Default Response

Status: 204 No Content

Notes

Preview notice

The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.hellcat-preview+json

List team projects

Lists the organization projects for a team. If you are an authenticated 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.

get /teams/{team_id}/projects

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notices

accept string header

This API is under preview and subject to change.
team_id integer path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.inertia-preview+json" \
  https://api.github.com/teams/42/projects
JavaScript (@octokit/core.js) 
await octokit.request('GET /teams/{team_id}/projects', {
  team_id: 42,
  mediaType: {
    previews: [
      'inertia'
    ]
  }
})

Default response

Status: 200 OK
[
  {
    "owner_url": "https://api.github.com/orgs/octocat",
    "url": "https://api.github.com/projects/1002605",
    "html_url": "https://github.com/orgs/api-playground/projects/1",
    "columns_url": "https://api.github.com/projects/1002605/columns",
    "id": 1002605,
    "node_id": "MDc6UHJvamVjdDEwMDI2MDU=",
    "name": "Organization Roadmap",
    "body": "High-level roadmap for the upcoming year.",
    "number": 1,
    "state": "open",
    "creator": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "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
    },
    "created_at": "2011-04-11T20:09:31Z",
    "updated_at": "2014-03-04T18:58:10Z",
    "organization_permission": "write",
    "private": false,
    "permissions": {
      "read": true,
      "write": true,
      "admin": false
    }
  }
]

Notes

Preview notices

The Projects API is currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.inertia-preview+json
☝️ This header is required.

The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.hellcat-preview+json

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.

get /teams/{team_id}/projects/{project_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notices

accept string header

This API is under preview and subject to change.
team_id integer path
project_id integer path

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.inertia-preview+json" \
  https://api.github.com/teams/42/projects/42
JavaScript (@octokit/core.js) 
await octokit.request('GET /teams/{team_id}/projects/{project_id}', {
  team_id: 42,
  project_id: 42,
  mediaType: {
    previews: [
      'inertia'
    ]
  }
})

Default response

Status: 200 OK
{
  "owner_url": "https://api.github.com/orgs/octocat",
  "url": "https://api.github.com/projects/1002605",
  "html_url": "https://github.com/orgs/api-playground/projects/1",
  "columns_url": "https://api.github.com/projects/1002605/columns",
  "id": 1002605,
  "node_id": "MDc6UHJvamVjdDEwMDI2MDU=",
  "name": "Organization Roadmap",
  "body": "High-level roadmap for the upcoming year.",
  "number": 1,
  "state": "open",
  "creator": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "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
  },
  "created_at": "2011-04-11T20:09:31Z",
  "updated_at": "2014-03-04T18:58:10Z",
  "organization_permission": "write",
  "private": false,
  "permissions": {
    "read": true,
    "write": true,
    "admin": false
  }
}

Response if project is not managed by this team

Status: 404 Not Found

Notes

Preview notices

The Projects API is currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.inertia-preview+json
☝️ This header is required.

The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.hellcat-preview+json

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.

put /teams/{team_id}/projects/{project_id}

Parameters

Name Type In Description
accept string header

This API is under preview and subject to change. See preview notices

accept string header

This API is under preview and subject to change.
team_id integer path
project_id integer path
permission string body

The permission to grant to the team for this project. Can be one of:
* read - team members can read, but not write to or administer this project.
* write - team members can read and write, but not administer this project.
* admin - team members can read, write and administer this project.
Default: the team's permission attribute will be used to determine what permission to grant the team on this project. 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."
Note: If you pass the hellcat-preview media type, you can promote—but not demote—a permission attribute inherited from a parent team.

Code samples

Shell 
curl \
  -X PUT \
  -H "Accept: application/vnd.github.inertia-preview+json" \
  https://api.github.com/teams/42/projects/42 \
  -d '{"permission":"permission"}'
JavaScript (@octokit/core.js) 
await octokit.request('PUT /teams/{team_id}/projects/{project_id}', {
  team_id: 42,
  project_id: 42,
  permission: 'permission',
  mediaType: {
    previews: [
      'inertia'
    ]
  }
})

Default Response

Status: 204 No Content

Response if the project is not owned by the organization

Status: 403 Forbidden
{
  "message": "Must have admin rights to Repository.",
  "documentation_url": "https://docs.github.com/enterprise-server@2.19/rest/reference/teams#add-or-update-team-project-permissions"
}

Notes

Preview notices

The Projects API is currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.inertia-preview+json
☝️ This header is required.

The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.hellcat-preview+json

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.

delete /teams/{team_id}/projects/{project_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

team_id integer path
project_id integer path

Code samples

Shell 
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/teams/42/projects/42
JavaScript (@octokit/core.js) 
await octokit.request('DELETE /teams/{team_id}/projects/{project_id}', {
  team_id: 42,
  project_id: 42
})

Default Response

Status: 204 No Content

Notes

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 site administrator for your Enterprise instance, you will be able to list all repositories for the team.

get /teams/{team_id}/repos

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended. See preview notice

team_id integer path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/teams/42/repos
JavaScript (@octokit/core.js) 
await octokit.request('GET /teams/{team_id}/repos', {
  team_id: 42
})

Default response

Status: 200 OK
[
  {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name":