Skip to content
forgit api docs

Create a team

POST
/orgs/{org}/teams

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

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
org
required
string

The organization name. The name is not case sensitive.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
name
required

The name of the team.

string
description

The description of the team.

string
maintainers

List GitHub usernames for organization members who will become team maintainers.

Array<string>
repo_names

The full name (e.g., “organization-name/repository-name”) of repositories to add the team to.

Array<string>
privacy

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
string
Allowed values: secret closed
notification_setting

The notification setting the team has chosen. The options are:

  • notifications_enabled - team members receive notifications when the team is @mentioned.
  • notifications_disabled - no one receives notifications.
    Default: notifications_enabled
string
Allowed values: notifications_enabled notifications_disabled
permission

Closing down notice. The permission that new repositories will be added to the team with when none is specified.

string
default: pull
Allowed values: pull push
parent_team_id

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

integer
Examples
Example default 
{
  "name": "Justice League",
  "description": "A great team",
  "permission": "push",
  "notification_setting": "notifications_enabled",
  "privacy": "closed"
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Response

Media type application/json
Full Team

Groups of organization members that gives permissions on specified repositories.

object
id
required

Unique identifier of the team

integer
node_id
required
string
url
required

URL for the team

string format: uri
html_url
required
string format: uri
name
required

Name of the team

string
slug
required
string
description
required
string
nullable
privacy

The level of privacy this team should have

string
Allowed values: closed secret
notification_setting

The notification setting the team has set

string
Allowed values: notifications_enabled notifications_disabled
permission
required

Permission that the team will have for its repositories

string
members_url
required
string
repositories_url
required
string format: uri
parent
Team Simple

Groups of organization members that gives permissions on specified repositories.

object
id
required

Unique identifier of the team

integer
node_id
required
string
url
required

URL for the team

string format: uri
members_url
required
string
name
required

Name of the team

string
description
required

Description of the team

string
nullable
permission
required

Permission that the team will have for its repositories

string
privacy

The level of privacy this team should have

string
notification_setting

The notification setting the team has set

string
html_url
required
string format: uri
repositories_url
required
string format: uri
slug
required
string
ldap_dn

Distinguished Name (DN) that team maps to within LDAP environment

string
type
required

The ownership type of the team

string
Allowed values: enterprise organization
organization_id

Unique identifier of the organization to which this team belongs

integer
enterprise_id

Unique identifier of the enterprise to which this team belongs

integer
members_count
required
integer
repos_count
required
integer
created_at
required
string format: date-time
updated_at
required
string format: date-time
organization
required
Team Organization

Team Organization

object
login
required
string
id
required
integer
node_id
required
string
url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string format: uri
hooks_url
required
string
issues_url
required
string
members_url
required
string
public_members_url
required
string
avatar_url
required
string
description
required
string
nullable
name
string
company
string
blog
string format: uri
location
string
email
string format: email
twitter_username
string
nullable
is_verified
boolean
has_organization_projects
required
boolean
has_repository_projects
required
boolean
public_repos
required
integer
public_gists
required
integer
followers
required
integer
following
required
integer
html_url
required
string format: uri
created_at
required
string format: date-time
type
required
string
total_private_repos
integer
owned_private_repos
integer
private_gists
integer
nullable
disk_usage
integer
nullable
collaborators
integer
nullable
billing_email
string format: email
nullable
plan
object
name
required
string
space
required
integer
private_repos
required
integer
filled_seats
integer
seats
integer
default_repository_permission
string
nullable
members_can_create_repositories
boolean
nullable
two_factor_requirement_enabled
boolean
nullable
members_allowed_repository_creation_type
string
members_can_create_public_repositories
boolean
members_can_create_private_repositories
boolean
members_can_create_internal_repositories
boolean
members_can_create_pages
boolean
members_can_create_public_pages
boolean
members_can_create_private_pages
boolean
members_can_fork_private_repositories
boolean
nullable
web_commit_signoff_required
boolean
updated_at
required
string format: date-time
archived_at
required
string format: date-time
nullable
ldap_dn

The distinguished name (DN) of the LDAP entry to map to a team.

string
type
required

The ownership type of the team

string
Allowed values: enterprise organization
organization_id

Unique identifier of the organization to which this team belongs

integer
enterprise_id

Unique identifier of the enterprise to which this team belongs

integer
Examples
Example default 
{
  "id": 1,
  "node_id": "MDQ6VGVhbTE=",
  "url": "https://api.github.com/teams/1",
  "html_url": "https://github.com/orgs/github/teams/justice-league",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "notification_setting": "notifications_enabled",
  "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",
    "is_verified": true,
    "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"
  }
}

403

Section titled “ 403 ”

Forbidden

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error

Validation Error

object
message
required
string
documentation_url
required
string
errors
Array<object>
object
resource
string
field
string
message
string
code
required
string
index
integer
value
One of:
string
nullable
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}