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](https://docs.github.com/en/articles/setting-team-creation-permissions-in-your-organization)." 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](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/about-teams)".

POST/orgs/{org}/teams

Source: github-v3-rest.json
Revision: f5f067c1e6f6
Active snapshot: 85e53e3d0d65

Request

Path Parameters

org string required

Body Params

required

application/jsonobject

description string

optional

The description of the team.

ldap_dn string

optional

The [distinguished name](https://www.ldap.com/ldap-dns-and-rdns) (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](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#update-ldap-mapping-for-a-team)" endpoint to change the LDAP DN. For more information, see "[Using LDAP](https://docs.github.com/[email protected]/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-ldap#enabling-ldap-sync)."

maintainers array[string]

optional

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

name string

required

The name of the team.

parent_team_id integer

optional

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

permission string

optional

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

Default: pull

Allowed: "pull""push"

privacy string

optional

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`

Allowed: "secret""closed"

repo_names array[string]

optional

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

Responses

application/json Full Team object

Response

created_at string<date-time>

required

Example: 2017-07-14T16:53:42Z

description string

requirednullable

Example: A great team.

html_url string<uri>

required

Example: https://github.com/orgs/rails/teams/core

id integer

required

Unique identifier of the team

Example: 42

ldap_dn string

optional

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

Example: uid=example,ou=users,dc=github,dc=com

members_count integer

required

Example: 3

members_url string

required

Example: https://api.github.com/organizations/1/team/1/members{/member}

name string

required

Name of the team

Example: Developers

node_id string

required

Example: MDQ6VGVhbTE=

organization Organization Full object

required

Organization Full

avatar_url string

required

Example: https://github.com/images/error/octocat_happy.gif

billing_email string<email>

optionalnullable

Example: [email protected]

blog string<uri>

optional

Example: https://github.com/blog

collaborators integer

optionalnullable

Example: 8

company string

optional

Example: GitHub

created_at string<date-time>

required

Example: 2008-01-14T04:33:35Z

default_repository_permission string

optionalnullable

description string

requirednullable

Example: A great organization

disk_usage integer

optionalnullable

Example: 10000

email string<email>

optional

Example: [email protected]

events_url string<uri>

required

Example: https://api.github.com/orgs/github/events

followers integer

required

Example: 20

following integer

required

Example: 0

has_organization_projects boolean

required

Example: true

has_repository_projects boolean

required

Example: true

hooks_url string

required

Example: https://api.github.com/orgs/github/hooks

html_url string<uri>

required

Example: https://github.com/octocat

id integer

required

Example: 1

is_verified boolean

optional

Example: true

issues_url string

required

Example: https://api.github.com/orgs/github/issues

location string

optional

Example: San Francisco

required

Example: github

members_allowed_repository_creation_type string

optional

Example: all

members_can_create_internal_repositories boolean

optional

Example: true

members_can_create_pages boolean

optional

Example: true

members_can_create_private_pages boolean

optional

Example: true

members_can_create_private_repositories boolean

optional

Example: true

members_can_create_public_pages boolean

optional

Example: true

members_can_create_public_repositories boolean

optional

Example: true

members_can_create_repositories boolean

optionalnullable

Example: true

members_can_fork_private_repositories boolean

optionalnullable

Example: false

members_url string

required

Example: https://api.github.com/orgs/github/members{/member}

name string

optional

Example: github

node_id string

required

Example: MDEyOk9yZ2FuaXphdGlvbjE=

owned_private_repos integer

optional

Example: 100

plan object

optional

filled_seats integer

optional

name string

required

private_repos integer

required

seats integer

optional

space integer

required

private_gists integer

optionalnullable

Example: 81

public_gists integer

required

Example: 1

public_members_url string

required

Example: https://api.github.com/orgs/github/public_members{/member}

public_repos integer

required

Example: 2

repos_url string<uri>

required

Example: https://api.github.com/orgs/github/repos

total_private_repos integer

optional

Example: 100

twitter_username string

optionalnullable

Example: github

two_factor_requirement_enabled boolean

optionalnullable

Example: true

type string

required

Example: Organization

updated_at string<date-time>

required

url string<uri>

required

Example: https://api.github.com/orgs/github

parent Team Simple object

optionalnullable

Groups of organization members that gives permissions on specified repositories.

description string

requirednullable

Description of the team

Example: A great team.

html_url string<uri>

required

Example: https://github.com/orgs/rails/teams/core

id integer

required

Unique identifier of the team

Example: 1

ldap_dn string

optional

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

Example: uid=example,ou=users,dc=github,dc=com

members_url string

required

Example: https://api.github.com/organizations/1/team/1/members{/member}

name string

required

Name of the team

Example: Justice League

node_id string

required

Example: MDQ6VGVhbTE=

permission string

required

Permission that the team will have for its repositories

Example: admin

privacy string

optional

The level of privacy this team should have

Example: closed

repositories_url string<uri>

required

Example: https://api.github.com/organizations/1/team/1/repos

slug string

required

Example: justice-league

url string<uri>

required

URL for the team

Example: https://api.github.com/organizations/1/team/1

permission string

required

Permission that the team will have for its repositories

Example: push

privacy string

optional

The level of privacy this team should have

Example: closed

Allowed: "closed""secret"

repos_count integer

required

Example: 10

repositories_url string<uri>

required

Example: https://api.github.com/organizations/1/team/1/repos

slug string

required

Example: justice-league

updated_at string<date-time>

required

Example: 2017-08-17T12:37:15Z

url string<uri>

required

URL for the team

Example: https://api.github.com/organizations/1/team/1

Response Example: 201 application/json

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

application/json Basic Error object

Forbidden

documentation_url string

optional

message string

optional

status string

optional

url string

optional

application/json Validation Error object

Validation failed

documentation_url string

required

errors array[object]

optional

items object

code string

required

field string

optional

index integer

optional

message string

optional

resource string

optional

value

optional

message string

required

Request configuration

This OpenAPI document does not declare an authentication scheme. Check the API provider's documentation before sending credentials; Manja cannot infer or validate an undocumented scheme.

Common bearer example: Authorization: Bearer YOUR_ACCESS_TOKEN

hostname

Self-hosted Enterprise Server or Enterprise Cloud hostname

protocol

Self-hosted Enterprise Server or Enterprise Cloud protocol

org *

Request Sample: Shell / cURL

curl --request POST \
  --url {protocol}://{hostname}/api/v3/orgs/{org}/teams \
  --header 'content-type: application/json' \
  --data '{
  "description": "A great team",
  "name": "Justice League",
  "permission": "push",
  "privacy": "closed"
}'