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 |
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://{hostname}/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
}
]
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
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 |
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 Enterprise 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: |
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
|
parent_team_id |
integer | body |
The ID of a team to set as the parent team. Note: You must pass the |
ldap_dn |
string | body |
The distinguished name (DN) of the LDAP entry to map to a team. LDAP synchronization must be enabled to map LDAP entries to a team. Use the Update LDAP mapping for a team endpoint to change the LDAP DN. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/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",
"parent": null,
"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",
"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
Get a team by name
Gets a team using the team's slug
. GitHub generates the slug
from the team name
.
get /orgs/{org}/teams/{team_slug}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
org |
string | path | |
team_slug |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/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",
"parent": null,
"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",
"type": "Organization"
},
"ldap_dn": "uid=asdf,ou=users,dc=github,dc=com"
}
Notes
get /teams/{team_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/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",
"parent": null,
"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",
"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 |
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 |
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
|
parent_team_id |
integer | body |
The ID of a team to set as the parent team. Note: You must pass the |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/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",
"parent": null,
"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",
"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 |
team_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/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. |
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://{hostname}/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. |
team_id |
integer | path | |
project_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.inertia-preview+json" \
https://{hostname}/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. |
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: |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.inertia-preview+json" \
https://{hostname}/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://developer.github.com/enterprise/2.18/v3/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 |
team_id |
integer | path | |
project_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/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 |
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://{hostname}/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": "octocat/Hello-World",
"owner": {
"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
},
"private": false,
"html_url": "https://github.com/octocat/Hello-World",
"description": "This your first repo!",
"fork": false,
"url": "https://api.github.com/repos/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"svn_url": "https://svn.github.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,
"is_template": true,
"topics": [
"octocat",
"atom",
"electron",
"api"
],
"has_issues": true,
"has_projects": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"archived": false,
"disabled": false,
"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
},
"template_repository": null,
"subscribers_count": 42,
"network_count": 0,
"anonymous_access_enabled": false,
"license": {
"key": "mit",
"name": "MIT License",
"spdx_id": "MIT",
"url": "https://api.github.com/licenses/mit",
"node_id": "MDc6TGljZW5zZW1pdA=="
}
}
]
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
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 via the Accept
header:
get /teams/{team_id}/repos/{owner}/{repo}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path | |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/teams/42/repos/octocat/hello-world
JavaScript (@octokit/core.js)
await octokit.request('GET /teams/{team_id}/repos/{owner}/{repo}', {
team_id: 42,
owner: 'octocat',
repo: 'hello-world'
})
Alternative response with extra repository information
Status: 200 OK
Response if repository is managed by this team
Status: 204 No Content
Response if repository is not managed by this team
Status: 404 Not Found
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
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."
put /teams/{team_id}/repos/{owner}/{repo}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path | |
owner |
string | path | |
repo |
string | path | |
permission |
string | body |
The permission to grant the team on this repository. Can be one of: If no permission is specified, the team's |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/teams/42/repos/octocat/hello-world \
-d '{"permission":"permission"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /teams/{team_id}/repos/{owner}/{repo}', {
team_id: 42,
owner: 'octocat',
repo: 'hello-world',
permission: 'permission'
})
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
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.
delete /teams/{team_id}/repos/{owner}/{repo}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path | |
owner |
string | path | |
repo |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/teams/42/repos/octocat/hello-world
JavaScript (@octokit/core.js)
await octokit.request('DELETE /teams/{team_id}/repos/{owner}/{repo}', {
team_id: 42,
owner: 'octocat',
repo: 'hello-world'
})
Default Response
Status: 204 No Content
Notes
List child teams
You must use the hellcat-preview
media type to use this endpoint.
get /teams/{team_id}/teams
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
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://{hostname}/teams/42/teams
JavaScript (@octokit/core.js)
await octokit.request('GET /teams/{team_id}/teams', {
team_id: 42
})
Response if child teams exist
Status: 200 OK
[
{
"id": 2,
"node_id": "MDQ6VGVhbTI=",
"url": "https://api.github.com/teams/2",
"name": "Original Roster",
"slug": "original-roster",
"description": "Started it all.",
"privacy": "closed",
"permission": "admin",
"members_url": "https://api.github.com/teams/2/members{/member}",
"repositories_url": "https://api.github.com/teams/2/repos",
"parent": {
"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"
}
}
]
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 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 when authenticating via OAuth.
get /user/teams
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
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://{hostname}/user/teams
JavaScript (@octokit/core.js)
await octokit.request('GET /user/teams')
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,
"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",
"type": "Organization"
},
"ldap_dn": "uid=asdf,ou=users,dc=github,dc=com"
}
]
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
Discussions
The team discussions API allows you to get, create, edit, and delete discussion posts on a team's page. You can use team discussions to have conversations that are not specific to a repository or project. Any member of the team's organization can create and read public discussion posts. For more details, see "About team discussions." To learn more about commenting on a discussion post, see the team discussion comments API. This API is only available to authenticated members of the team's organization.
List discussions
List all discussions on a team's page. OAuth access tokens require the read:discussion
scope.
get /teams/{team_id}/discussions
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notices. |
team_id |
integer | path | |
direction |
string | query |
Sorts the discussion comments by the date they were created. To return the oldest comments first, set to |
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.echo-preview+json" \
https://{hostname}/teams/42/discussions
JavaScript (@octokit/core.js)
await octokit.request('GET /teams/{team_id}/discussions', {
team_id: 42,
mediaType: {
previews: [
'echo'
]
}
})
Default response
Status: 200 OK
[
{
"author": {
"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
},
"body": "Hi! This is an area for us to collaborate as a team.",
"body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
"body_version": "0d495416a700fb06133c612575d92bfb",
"comments_count": 0,
"comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
"created_at": "2018-01-25T18:56:31Z",
"last_edited_at": null,
"html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
"node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
"number": 1,
"pinned": false,
"private": false,
"team_url": "https://api.github.com/teams/2343027",
"title": "Our first team post",
"updated_at": "2018-01-25T18:56:31Z",
"url": "https://api.github.com/teams/2343027/discussions/1",
"reactions": {
"url": "https://api.github.com/teams/2343027/discussions/1/reactions",
"total_count": 5,
"+1": 3,
"-1": 1,
"laugh": 0,
"confused": 0,
"heart": 1,
"hooray": 0
}
}
]
Notes
Preview notices
The team discussions API is currently available for developers to preview. 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.echo-preview+json
☝️ This header is required.
An additional reactions
object in the issue comment payload is currently available for developers to preview. During
the preview period, the APIs may change without advance notice. Please 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.squirrel-girl-preview
The reactions
key will have the following payload where url
can be used to construct the API location for listing
and creating reactions.
{
"total_count": 5,
"+1": 3,
"-1": 1,
"laugh": 0,
"confused": 0,
"heart": 1,
"hooray": 0,
"url": "https://api.github.com/repos/octocat/Hello-World/issues/1347/reactions"
}
Create a discussion
Creates a new discussion post on a team's page. OAuth access tokens require the write:discussion
scope.
This endpoint triggers notifications. Creating content too quickly using this endpoint may result in abuse rate limiting. See "Abuse rate limits" for details.
post /teams/{team_id}/discussions
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notices. |
team_id |
integer | path | |
title |
string | body |
Required. The discussion post's title. |
body |
string | body |
Required. The discussion post's body text. |
private |
boolean | body |
Private posts are only visible to team members, organization owners, and team maintainers. Public posts are visible to all members of the organization. Set to |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.echo-preview+json" \
https://{hostname}/teams/42/discussions \
-d '{"title":"title","body":"body"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /teams/{team_id}/discussions', {
team_id: 42,
title: 'title',
body: 'body',
mediaType: {
previews: [
'echo'
]
}
})
Default response
Status: 201 Created
{
"author": {
"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
},
"body": "Hi! This is an area for us to collaborate as a team.",
"body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
"body_version": "0d495416a700fb06133c612575d92bfb",
"comments_count": 0,
"comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
"created_at": "2018-01-25T18:56:31Z",
"last_edited_at": null,
"html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
"node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
"number": 1,
"pinned": false,
"private": false,
"team_url": "https://api.github.com/teams/2343027",
"title": "Our first team post",
"updated_at": "2018-01-25T18:56:31Z",
"url": "https://api.github.com/teams/2343027/discussions/1",
"reactions": {
"url": "https://api.github.com/teams/2343027/discussions/1/reactions",
"total_count": 5,
"+1": 3,
"-1": 1,
"laugh": 0,
"confused": 0,
"heart": 1,
"hooray": 0
}
}
Notes
Preview notices
The team discussions API is currently available for developers to preview. 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.echo-preview+json
☝️ This header is required.
An additional reactions
object in the issue comment payload is currently available for developers to preview. During
the preview period, the APIs may change without advance notice. Please 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.squirrel-girl-preview
The reactions
key will have the following payload where url
can be used to construct the API location for listing
and creating reactions.
{
"total_count": 5,
"+1": 3,
"-1": 1,
"laugh": 0,
"confused": 0,
"heart": 1,
"hooray": 0,
"url": "https://api.github.com/repos/octocat/Hello-World/issues/1347/reactions"
}
Get a discussion
Get a specific discussion on a team's page. OAuth access tokens require the read:discussion
scope.
get /teams/{team_id}/discussions/{discussion_number}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notices. |
team_id |
integer | path | |
discussion_number |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.echo-preview+json" \
https://{hostname}/teams/42/discussions/42
JavaScript (@octokit/core.js)
await octokit.request('GET /teams/{team_id}/discussions/{discussion_number}', {
team_id: 42,
discussion_number: 42,
mediaType: {
previews: [
'echo'
]
}
})
Default response
Status: 200 OK
{
"author": {
"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
},
"body": "Hi! This is an area for us to collaborate as a team.",
"body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
"body_version": "0d495416a700fb06133c612575d92bfb",
"comments_count": 0,
"comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
"created_at": "2018-01-25T18:56:31Z",
"last_edited_at": null,
"html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
"node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
"number": 1,
"pinned": false,
"private": false,
"team_url": "https://api.github.com/teams/2343027",
"title": "Our first team post",
"updated_at": "2018-01-25T18:56:31Z",
"url": "https://api.github.com/teams/2343027/discussions/1",
"reactions": {
"url": "https://api.github.com/teams/2343027/discussions/1/reactions",
"total_count": 5,
"+1": 3,
"-1": 1,
"laugh": 0,
"confused": 0,
"heart": 1,
"hooray": 0
}
}
Notes
Preview notices
The team discussions API is currently available for developers to preview. 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.echo-preview+json
☝️ This header is required.
An additional reactions
object in the issue comment payload is currently available for developers to preview. During
the preview period, the APIs may change without advance notice. Please 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.squirrel-girl-preview
The reactions
key will have the following payload where url
can be used to construct the API location for listing
and creating reactions.
{
"total_count": 5,
"+1": 3,
"-1": 1,
"laugh": 0,
"confused": 0,
"heart": 1,
"hooray": 0,
"url": "https://api.github.com/repos/octocat/Hello-World/issues/1347/reactions"
}
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.
patch /teams/{team_id}/discussions/{discussion_number}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notices. |
team_id |
integer | path | |
discussion_number |
integer | path | |
title |
string | body |
The discussion post's title. |
body |
string | body |
The discussion post's body text. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.echo-preview+json" \
https://{hostname}/teams/42/discussions/42 \
-d '{"title":"title"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /teams/{team_id}/discussions/{discussion_number}', {
team_id: 42,
discussion_number: 42,
title: 'title',
mediaType: {
previews: [
'echo'
]
}
})
Default response
Status: 200 OK
{
"author": {
"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
},
"body": "Hi! This is an area for us to collaborate as a team.",
"body_html": "<p>Hi! This is an area for us to collaborate as a team</p>",
"body_version": "0d495416a700fb06133c612575d92bfb",
"comments_count": 1,
"comments_url": "https://api.github.com/teams/2343027/discussions/1/comments",
"created_at": "2018-01-25T18:56:31Z",
"last_edited_at": "2018-01-26T18:22:20Z",
"html_url": "https://github.com/orgs/github/teams/justice-league/discussions/1",
"node_id": "MDE0OlRlYW1EaXNjdXNzaW9uMQ==",
"number": 1,
"pinned": false,
"private": false,
"team_url": "https://api.github.com/teams/2343027",
"title": "Welcome to our first team post",
"updated_at": "2018-01-26T18:22:20Z",
"url": "https://api.github.com/teams/2343027/discussions/1",
"reactions": {
"url": "https://api.github.com/teams/2343027/discussions/1/reactions",
"total_count": 5,
"+1": 3,
"-1": 1,
"laugh": 0,
"confused": 0,
"heart": 1,
"hooray": 0
}
}
Notes
Preview notices
The team discussions API is currently available for developers to preview. 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.echo-preview+json
☝️ This header is required.
An additional reactions
object in the issue comment payload is currently available for developers to preview. During
the preview period, the APIs may change without advance notice. Please 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.squirrel-girl-preview
The reactions
key will have the following payload where url
can be used to construct the API location for listing
and creating reactions.
{
"total_count": 5,
"+1": 3,
"-1": 1,
"laugh": 0,
"confused": 0,
"heart": 1,
"hooray": 0,
"url": "https://api.github.com/repos/octocat/Hello-World/issues/1347/reactions"
}
Delete a discussion
Delete a discussion from a team's page. OAuth access tokens require the write:discussion
scope.
delete /teams/{team_id}/discussions/{discussion_number}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
team_id |
integer | path | |
discussion_number |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.echo-preview+json" \
https://{hostname}/teams/42/discussions/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /teams/{team_id}/discussions/{discussion_number}', {
team_id: 42,
discussion_number: 42,
mediaType: {
previews: [
'echo'
]
}
})
Default Response
Status: 204 No Content
Notes
Preview notice
The team discussions API is currently available for developers to preview. 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.echo-preview+json
☝️ This header is required.
Discussion comments
The team discussion comments API allows you to get, create, edit, and delete discussion comments on a team discussion post. Any member of the team's organization can create and read comments on a public discussion. For more details, see "About team discussions." This API is only available to authenticated members of the team's organization.
Mitglieder
This API is only available to authenticated members of the team's organization. OAuth access tokens require the read:org
scope.
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 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."
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.
get /teams/{team_id}/members
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path | |
role |
string | query |
Filters members returned by their role in the team. Can be one of: |
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://{hostname}/teams/42/members
JavaScript (@octokit/core.js)
await octokit.request('GET /teams/{team_id}/members', {
team_id: 42
})
Default response
Status: 200 OK
[
{
"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
}
]
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
Get team member (Legacy)
The "Get team member" endpoint (described below) is deprecated.
We recommend using the 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 /teams/{team_id}/members/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path | |
username |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/teams/42/members/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('GET /teams/{team_id}/members/{username}', {
team_id: 42,
username: 'username'
})
Response if user is a member
Status: 204 No Content
Response if user is not a member
Status: 404 Not Found
Notes
Add team member (Legacy)
The "Add team member" endpoint (described below) is deprecated.
We recommend using the Add or update team membership for a user endpoint instead. It allows you to invite new organization members to your teams.
To add someone to a team, the authenticated user must be an organization owner or a team maintainer in the team they're changing. The person being added to the team must be a member of the team's organization.
Note that you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP verbs."
put /teams/{team_id}/members/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path | |
username |
string | path |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/teams/42/members/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('PUT /teams/{team_id}/members/{username}', {
team_id: 42,
username: 'username'
})
Default Response
Status: 204 No Content
Response if you attempt to add an organization to a team
Status: 422 Unprocessable Entity
{
"message": "Cannot add an organization as a member.",
"errors": [
{
"code": "org",
"field": "user",
"resource": "TeamMember"
}
]
}
Response if 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
Status: 422 Unprocessable Entity
{
"message": "User isn't a member of this organization. Please invite them first.",
"errors": [
{
"code": "unaffiliated",
"field": "user",
"resource": "TeamMember"
}
]
}
Notes
Remove team member (Legacy)
The "Remove team member" endpoint (described below) is deprecated.
We recommend using the Remove team membership for a user endpoint instead. It allows you to remove both active and pending memberships.
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.
delete /teams/{team_id}/members/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path | |
username |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/teams/42/members/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /teams/{team_id}/members/{username}', {
team_id: 42,
username: 'username'
})
Default Response
Status: 204 No Content
Notes
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 role
for organization owners returns as maintainer
. For more information about maintainer
roles, see Create a team.
get /teams/{team_id}/memberships/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path | |
username |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/teams/42/memberships/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('GET /teams/{team_id}/memberships/{username}', {
team_id: 42,
username: 'username'
})
Response if user has an active membership with team
Status: 200 OK
{
"url": "https://api.github.com/teams/1/memberships/octocat",
"role": "member",
"state": "active"
}
Response if user is a team maintainer
Status: 200 OK
{
"url": "https://api.github.com/teams/1/memberships/octocat",
"role": "maintainer",
"state": "active"
}
Response if user has a pending membership with team
Status: 200 OK
{
"url": "https://api.github.com/teams/1/memberships/octocat",
"role": "member",
"state": "pending"
}
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
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.
put /teams/{team_id}/memberships/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path | |
username |
string | path | |
role |
string | body |
The role that this user should have in the team. Can be one of: member
|
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/teams/42/memberships/USERNAME \
-d '{"role":"role"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /teams/{team_id}/memberships/{username}', {
team_id: 42,
username: 'username',
role: 'role'
})
Response if user's membership with team is now active
Status: 200 OK
{
"url": "https://api.github.com/teams/1/memberships/octocat",
"role": "member",
"state": "active"
}
Response if user's membership with team is now pending
Status: 200 OK
{
"url": "https://api.github.com/teams/1/memberships/octocat",
"role": "member",
"state": "pending"
}
Response if you attempt to add an organization to a team
Status: 422 Unprocessable Entity
{
"message": "Cannot add an organization as a member.",
"errors": [
{
"code": "org",
"field": "user",
"resource": "TeamMember"
}
]
}
Notes
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.
delete /teams/{team_id}/memberships/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
team_id |
integer | path | |
username |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/teams/42/memberships/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /teams/{team_id}/memberships/{username}', {
team_id: 42,
username: 'username'
})
Default Response
Status: 204 No Content
Notes
Team synchronization
The Team Synchronization API allows you to manage connections between GitHub Enterprise teams and external identity provider (IdP) groups. To use this API, the authenticated user must be a team maintainer or an owner of the organization associated with the team. The token you use to authenticate will also need to be authorized for use with your IdP (SSO) provider. For more information, see "Authorizing a personal access token for use with a SAML single sign-on organization."
You can manage GitHub team members through your IdP with team synchronization. Team synchronization must be enabled to use the Team Synchronization API. For more information, see "Synchronizing teams between your identity provider and GitHub."