# Create a team

From **GitHub v3 REST API**.

`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](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)".

## Parameters

### `org`

- Location: path
- Required: true
- Type: `string`

## Request body

- Required: true
### `application/json`

- Type: `object`

```json
{
  "description": "A great team",
  "name": "Justice League",
  "permission": "push",
  "privacy": "closed"
}
```

```json
{"properties":{"description":{"description":"The description of the team.","type":"string"},"ldap_dn":{"description":"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/enterprise-server@3.0/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/enterprise-server@3.0/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-ldap#enabling-ldap-sync).\"","type":"string"},"maintainers":{"description":"List GitHub IDs for organization members who will become team maintainers.","items":{"type":"string"},"type":"array"},"name":{"description":"The name of the team.","type":"string"},"parent_team_id":{"description":"The ID of a team to set as the parent team.","type":"integer"},"permission":{"default":"pull","description":"**Deprecated**. The permission that new repositories will be added to the team with when none is specified. Can be one of:  \n\\* `pull` - team members can pull, but not push to or administer newly-added repositories.  \n\\* `push` - team members can pull and push, but not administer newly-added repositories.","enum":["pull","push"],"type":"string"},"privacy":{"description":"The level of privacy this team should have. The options are:  \n**For a non-nested team:**  \n\\* `secret` - only visible to organization owners and members of this team.  \n\\* `closed` - visible to all members of this organization.  \nDefault: `secret`  \n**For a parent or child team:**  \n\\* `closed` - visible to all members of this organization.  \nDefault for child team: `closed`","enum":["secret","closed"],"type":"string"},"repo_names":{"description":"The full name (e.g., \"organization-name/repository-name\") of repositories to add the team to.","items":{"type":"string"},"type":"array"}},"required":["name"],"type":"object"}
```

## Responses

### `201`

Response

### `application/json`

- Type: `object`

Groups of organization members that gives permissions on specified repositories.

```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": "octocat@github.com",
    "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"
}
```

```json
{"description":"Groups of organization members that gives permissions on specified repositories.","properties":{"created_at":{"example":"2017-07-14T16:53:42Z","format":"date-time","type":"string"},"description":{"example":"A great team.","nullable":true,"type":"string"},"html_url":{"example":"https://github.com/orgs/rails/teams/core","format":"uri","type":"string"},"id":{"description":"Unique identifier of the team","example":42,"type":"integer"},"ldap_dn":{"description":"Distinguished Name (DN) that team maps to within LDAP environment","example":"uid=example,ou=users,dc=github,dc=com","type":"string"},"members_count":{"example":3,"type":"integer"},"members_url":{"example":"https://api.github.com/organizations/1/team/1/members{/member}","type":"string"},"name":{"description":"Name of the team","example":"Developers","type":"string"},"node_id":{"example":"MDQ6VGVhbTE=","type":"string"},"organization":{"$ref":"#/components/schemas/organization-full"},"parent":{"$ref":"#/components/schemas/nullable-team-simple"},"permission":{"description":"Permission that the team will have for its repositories","example":"push","type":"string"},"privacy":{"description":"The level of privacy this team should have","enum":["closed","secret"],"example":"closed","type":"string"},"repos_count":{"example":10,"type":"integer"},"repositories_url":{"example":"https://api.github.com/organizations/1/team/1/repos","format":"uri","type":"string"},"slug":{"example":"justice-league","type":"string"},"updated_at":{"example":"2017-08-17T12:37:15Z","format":"date-time","type":"string"},"url":{"description":"URL for the team","example":"https://api.github.com/organizations/1/team/1","format":"uri","type":"string"}},"required":["id","node_id","url","members_url","name","description","permission","html_url","repositories_url","slug","created_at","updated_at","members_count","repos_count","organization"],"title":"Full Team","type":"object"}
```

### `403`

Forbidden

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error

```json
{"description":"Validation Error","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"index":{"type":"integer"},"message":{"type":"string"},"resource":{"type":"string"},"value":{"oneOf":[{"nullable":true,"type":"string"},{"nullable":true,"type":"integer"},{"items":{"type":"string"},"nullable":true,"type":"array"}]}},"required":["code"],"type":"object"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error","type":"object"}
```

## Request examples

### cURL

```shell
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"
}'
```